pycopancore reduced to core

.gitignore

@@ -29,6 +29,7 @@ eggs/
 .eggs/
 lib/
 lib64/
+.vscode/
 parts/
 sdist/
 var/
@@ -71,6 +72,7 @@ docs/_build/
 _build/*
 _build
 
+
 # PyBuilder
 target/
 

CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: If you use this software, please cite it using the metadata from this file.
 type: software
 title: 'pycopancore: Reference implementation of the copan:CORE World-Earth modelling framework'
-version: 0.7.0
-date-released: '2024-07-04'
+version: 0.8.0
+date-released: '2025-01-28'
 abstract: The pycopancore package is a python implementation of the copan:CORE
   modeling framework as described in this paper. The framework is designed to
   allow an easy implementation of World-Earth (i.e., global social-ecological)
@@ -14,6 +14,18 @@ abstract: The pycopancore package is a python implementation of the copan:CORE
   stochastic and deterministic events and therefore allows to compare different
   model and component types and implementations.
 authors:
+- family-names: Breier
+  given-names: Jannes
+  email: jannesbr@pik-potsdam.de
+  orcid: 0000-0002-9055-6904
+- family-names: Schwarz
+  given-names: Luana
+  email: lschwarz@pik-potsdam.de
+  orcid: 0000-0003-1726-1509
+- family-names: Hotz
+  given-names: Ronja
+  email: ronja.hotz@kit.edu
+  orcid: 0000-0003-3425-268X
 - family-names: Bechthold
   given-names: Max
   email: maxbecht@pik-potsdam.de

docs/Makefile

@@ -6,6 +6,7 @@ SPHINXOPTS    = -E -a
 SPHINXBUILD   = sphinx-build
 PYREVERSE = pyreverse
 APIDOC = sphinx-apidoc
+APIDOCOPTS = -l -d 2 -e -P -M -f -o ./docs/_api 
 SPHINX_APIDOC_OPTIONS=members,undoc-members,private-members,special-members,inherited-members,show-inheritance
 DOT = dot
 PAPER         =
@@ -61,7 +62,7 @@ clean:
 .PHONY: html
 html:
 	@echo "Creating auto-generated documentation from source"
-	cd ..; $(APIDOC) --implicit-namespaces -f -o ./docs/_api ./pycopancore/ ./pycopancore/model_components/base/__init__.py ./pycopancore/model_components/seven_dwarfs/__init__.py
+	cd ..; $(APIDOC) $(APIDOCOPTS) --implicit-namespaces ./pycopancore/ #./pycopancore/model_components/base/__init__.py ./pycopancore/model_components/seven_dwarfs/__init__.py
 	@echo
 	@echo "Sphinx-apidoc is done, building directories"
 	$(SPHINXBUILD) -b html -v $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -71,7 +72,7 @@ html:
 .PHONY: api
 api:
 	@echo
-	cd ..; $(APIDOC) -f -o ./docs/_api ./pycopancore/
+	cd ..; $(APIDOC) $(APIDOCOPTS) ./docs/_api ./pycopancore/
 
 .PHONY : uml
 uml:

docs/conf.py

@@ -44,7 +44,7 @@
 
 # Napoleon settings
 napoleon_numpy_docstring = True
-napoleon_google_docstring = False
+napoleon_google_docstring = True
 napoleon_include_special_with_doc = True
 # more info at http://www.sphinx-doc.org/en/stable/ext/
 #                   napoleon.html#module-sphinx.ext.napoleon
@@ -54,14 +54,15 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+#source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
+root_doc = 'index'
 
 # General information about the project.
 project = u'pycopancore'
@@ -100,15 +101,15 @@
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+show_authors = True
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -185,19 +186,19 @@
 html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
-#html_split_index = False
+html_split_index = True
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the

docs/index.rst

@@ -18,7 +18,7 @@ Contents:
 .. TODO: move introduction to inside this page so that it is more immediately available for reading?
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
    :titlesonly:
 
    introduction

pycopancore/__init__.py

@@ -9,14 +9,4 @@
 #
 # URL: <http://www.pik-potsdam.de/copan/software>
 # Contact: core@pik-potsdam.de
-# License: BSD 2-clause license
-
-from .data_model import *
-from .process_types import *
-from .runners import *
-from .util import *
-
-from .model_components import base
-
-__url__ = "http://www.pik-potsdam.de/copan/software"
-__version__ = "0.1.0"
+# License: BSD 2-clause license

pycopancore/data_model/__init__.py

@@ -1,3 +1,73 @@
+"""
+==========
+Data model
+==========
+
+**************************
+Variable naming convention
+**************************
+
+We suggest to use rather descriptive variable names that make the relevant
+dimension clear in the following fashion:
+
+* Variables that represent integer cardinalities should be called **numbers**
+  (possibly abbreviated as `n`, `no`, or `num`) or **counts**.
+
+* Extensive variables of simple physical dimension should be called **stocks**, 
+  e.g. `atmospheric_carbon_stock` of dimension `carbon` and default unit `GtC`,
+  or `physical_capital_stock` of dimension `monetary_value` and default unit `dollars`.
+
+* Intensive variables of simple physical dimension should *not* be called 'stocks'
+  to distinguish them from extensive variables. E.g. `surface_air_temperature` 
+  of dimension `temperature` and default unit `kelvins`.
+
+* Variables that represent a stock per surface area, volume, or mass should be
+  called **densities**, e.g., `vegetation_carbon_density` in `GtC/m2` or
+  `energy_density_of_wood` in `MJ/kg`.
+
+* Variables that represent (changes of) stocks per time or time derivatives of stocks
+  should be called **flows**, e.g. `photosynthesis_carbon_flow` of dimension
+  `carbon/time` and default unit `GtC/yr`, or `income_flow` of dimension `money/time`
+  and default unit `dollars/yr`.
+
+* Variables that represent flows per surface area should be called **fluxes**,
+  e.g. `sensible_heat_flux` of dimension `energy/time/area` and default unit
+  `W/m^2`.
+
+* Variables of dimension `time` that represent specific unique time points
+  should be called **time_points** or **dates**, e.g., `net_zero_date`.
+
+* Variables of dimension `time` that represent amounts of time *between*
+  time points should be called **delays**, **intervals**, **durations**, 
+  **periods**, **ages**, etc., or sometimes just **times**.
+  e.g. `business_cycle_period` or `Individual.age`.
+
+* Variables of dimension `1/time` referring to periodic occurrences should be
+  called **frequencies**, i.e., `voting_frequency`.
+
+* Other variables of dimension `1/time` should be called **rates**, e.g.
+  `equilibration_rate`, `discount_rate`, `depreciation_rate`, `diffusion_rate`.
+  Variables of other dimension than `1/time`, in particular fractions or ratios, 
+  should *not* be called 'rates'.
+
+* Dimensionless variables between 0 and 1 that represent parts of a whole
+  should be called **fractions** or **shares**, e.g. `dirty_fraction` or 
+  `fossil_energy_share`.
+
+* Dimensionless variables that represent the relative size of one quantity as
+  compared to another quantity of the same dimension should be called **ratios**,
+  e.g., `cost_benefit_ratio`.
+
+* Variables representing the derivative of one quantity w.r.t. another quantity
+  (other than time) should be called **sensitivities**, e.g.
+  `temperature_sensitivity_of_photosynthesis`.
+
+* Variables representing the derivative of the *logarithm* of one quantity w.r.t.
+  the logarithm of another quantity should be called **elasticities**, e.g.
+  `labor_elasticity_of_fossil_energy_production`.
+"""
+
+
 # This file is part of pycopancore.
 #
 # Copyright (C) 2016-2017 by COPAN team at Potsdam Institute for Climate

pycopancore/data_model/dimensional_quantity.py

@@ -9,8 +9,8 @@
 # Contact: core@pik-potsdam.de
 # License: BSD 2-clause license
 
-from . import dimension
-from . import unit as U
+from pycopancore.data_model import dimension
+from pycopancore.data_model import unit as U
 
 
 class DimensionalQuantity(object):

pycopancore/data_model/master_data_model/__init__.py

@@ -41,4 +41,3 @@
 from .group import Group as group
 from .group import Group
 
-from .. import unity

pycopancore/data_model/master_data_model/cell.py

@@ -9,16 +9,20 @@
 # Contact: core@pik-potsdam.de
 # License: BSD 2-clause license
 
-from . import ENV, MET
-from . import square_kilometers
+from pycopancore.data_model.master_data_model.environment \
+    import Environment as ENV
+from pycopancore.data_model.master_data_model.metabolism \
+    import Metabolism as MET
+from pycopancore.data_model.master_data_model.dimensions_and_units \
+    import DimensionsAndUnits as DAU
 
 
 class Cell:
 
     # natural:
 
     land_area = ENV.land_area.copy()
-    land_area.default = 1 * square_kilometers
+    land_area.default = 1 * DAU.km2
     atmospheric_carbon = ENV.atmospheric_carbon.copy()
     surface_air_temperature = ENV.surface_air_temperature.copy()
     ocean_carbon = ENV.ocean_carbon.copy()

pycopancore/data_model/master_data_model/culture.py

@@ -9,11 +9,10 @@
 # Contact: core@pik-potsdam.de
 # License: BSD 2-clause license
 
-from .. import Variable
-
 from networkx import DiGraph, Graph
 
-from .. import unity
+from pycopancore.data_model.variable import Variable
+from pycopancore.data_model.unit import unity
 
 
 class Culture: