pik-copan / pycopancore Goto Github PK

Write a plotting component which works with the trajectory dictionary which is returned by the runner.

As @mensch72 mentioned in #27, a model fact sheet following the guidelines here should be created.

PS: As it's unrelated to #27, I made a new issue for this.

In perspective ...

After the meeting, I was discussing with Wolf and he asked me to Draft a first Code of Good Practice for coding, that we could put in the README. The idea is to have some guidelines/recommendations/hints that we want to follow so the code is legible, easy to debug and easy to expand.
PS: I can't assign myself, could somebody with the correct rights do that?

The test-environment is set up, now we need to write some test, maybe also a test template

This is a question that came to my mind lately. When initializing the model, where do we have creation routines of cells etc.? At low levels, so for example at the planet or donut_world class that creates a grid or - in case of individuals - a network that includes individuals? Or at model level?

I prefer creating instances at lower level to make the model class more manageable, but I see probels with this idea too: So in my example, the donut_world class is made to work with the local_renewable_resource class. With another class it may not work...

I am not shure how connected these problems are, because I don't have a clear picture of the model structure in detail in my mind, yet. Maybe we can discuss this soon, I think otherwise we will have inconsequent structure later

Since now we are programming a lot in single classes without using them, it might be the right time to write some unit-test? If so, do we put them into the tests folder and name them something like filename_test.py? Or folder_filename_test.py? Is there an established naming scheme?

While going through the code Svenja noticed some confusing use of naming. This led us to start a general discussion about it.

Each underlying class (Cell, Society, Individual, Nature, Culture, Metabolism) has an attribute called entities, which is a list containing the classes' instances. Since only objects of the classes Society, Individual and Cell should be called entities we have to find another name for this list.

Any suggestions?

Implement the option to raise events caused by a process during a integration. Until now the time an event takes place is decided before, a sudden event is not possible. Runner-logic must be changed to allow for this.

Check for sphinx plugins.

Maybe include mandatory naming of variables when calling functions. Assure that this is the case for all functions by using the testing environment

#25 depends on the implementation of a MasterDataModel, where variables which are used by several components are defined

Think about content, journal, length etc.

Check PIK best practice documents on open source licenses.

From PIK's open source recommendations: "use http://contributoragreements.org to create a contributor agreement". They recommend the following settings:

• Non-exclusive license: Giving the project owner the right to relicense it but does not retract any rights of the contributor on their contribution
• Permission to relicense the code under any Open Source license which is either approved by the Free Software Foundation or Open Source Initiative (Option 3).
• Permission to license provided documentations under cc-by (http://creativecommons.org/licenses/)
• Traditional patent licensing agreement

I implemented a second ODE in dummy/cell.py. It turned out that the model can't handle that yet. I pushed the model setup with two ODEs to the branch "2ode_bug, so that you can check it out @tillkolster.

If there are any suggestion to improve or enhance the existing code leave them here.

Edit by Till:
This is just a thread to collect pieces of code to show how there is a more elegant way and to keep them as a sort of style guide by examples

How to represent network between different model entities ?

Goal: Allow for...

• flexible addition of model variables (including static ones aka parameters) by model components
• easy usage in other model components
• possibility to be promoted into a centrally governed "master data model"
• without having to maintain a variable's metadata (name, description, dimension, unit, scale type, bounds, quantum, default value, uninformed prior distribution, etc.) in more than one place.

1. A new model variable (e.g. Cell.fossil_reserve) comes into being when some model component (e.g. pycopancore.components.fossil_extraction) introduces it the first time by defining it in their entity interface class by instantiating the Variable class with the variable's metadata, e.g. in pycopancore.components.fossil_extraction.interface.py:

class Cell (object):
    fossil_reserve = Variable(name="cellular fossil reserve", desc="...", dimension=Carbon)

2. Another components (e.g. pycopancore.components.general_equilibrium_energy_sector) can then access that variable by importing that interface module in its own interface module and assigning the same Variable object to its own entity interface class, e.g. in pycopancore.components.general_equilibrium_energy_sector.interface.py:

import pycopancore.components.fossil_extraction.interface as FE
class Cell (object):
     fossil_reserve = FE.Cell.fossil_reserve

3. As soon as the variable gets approved by the copancore-community's "data model committee" (to be defined), its definition gets copied into the master data model, a special module of the same format as the components' interface modules, whose classes are however never inherited directly. In the above example, on would then add to pycopancore.master_data_model.py:

class Cell (object):
    fossil_reserve = Variable(name="cellular fossil reserve", desc="...", dimension=Carbon)

4. From that point on, all components using this variable should import it from the master data model, e.g., both pycopancore.components.fossil_extraction.interface.py and pycopancore.components.general_equilibrium_energy_sector.interface.py would change to

import pycopancore.master_data_model as MDM
class Cell (object):
     fossil_reserve = MDM.Cell.fossil_reserve

5. To maintain harmonized variable definitions and avoid coincidental name clashes, the method Model.configure() must make sure that if two of the components used in the model at hand define the same variable name, it must point to the same Variable object (as in the examples above). It may even make sure that if a component uses a variable name that exists in the MDM, it must point to the Variable object defined in the MDM.

6. Still, components should probably be allowed to use another component's (or the master data model's) variables under a locally different name, as in:

import pycopancore.components.fossil_extraction.interface as FE
class Cell (object):
     geological_carbon_stock = FE.Cell.fossil_reserve

How does time integration work in the model? What integrator to use? (Frank has an alpha version of a solver of algebro-differential equations)

Basic problem / challenge of combining continuous and irregularly discrete dynamics.

Either

• copancore
  • anthroposphere
    • abstract_anthoposphere.py
    • concrete_athroposphere_1.py
    • concrete_athroposphere_2.py
    • ...
  • ecosphere
    • abstract_ecosphere.py
    • concrete_ecosphere_1.py
    • concrete_ecosphere_2.py
    • ...

or

• copancore
  • abstract_anthoposphere.py
  • abstract_ecosphere.py
  • concrete_model_1
    • concrete_anthroposphere_1.py
    • concrete_ecosphere_1.py
  • concrete_model_2
    • ....
  • ...

Jede Entity hat ein Attribut, zu welcher World es gehört. Da das ja bei jeder Entity ausser bei World selber nötig ist, ist das nun im Branch https://github.com/pik-copan/pycopancore/tree/world_entity_type (world_entity_type) in der Abstract_Entity_Mixin Klasse implementiert. Jetzt gibt es nur den Schönheitsfehler, dass man beim Initialisieren von world selber auch etwas angeben muss um dieses Attribut zu füllen, derzeit ist das mit None gemacht. Das ist aber nicht schön. Wie kann man das schöner machen?

As in the exploit model, some models might terminate on their own (before the end time t_1) where the runner should stop execution.
How do we pass this to the runner?

Any suggestions @mensch72 ?

What is a recommended way to handle networks in CORE components: use a performant, but simple library for this: igraph, graphtool, boostgraph ? Check what is recommended and define criteria for selection.

• rename to _template so that it is not confused with actual model components
• add __deactivate and __reactivate method templates to all entity types
• remove as much clutter as possible
• rewrite docstrings so that they are templates for the later docstrings rather than explain what needs to be done
• add comments beginning "TODO:" that explain what needs to be done to make a component on the basis of the _template. the model component developer would later remove these comments
• merge some of the minor improvements Jobst did in the prototype branch

Enhance the templates and their documentation to make it easier for newbies to work with the framework. Maybe this is to be done when developing a new component, so nothing is forgotten to be included

• naming of variables: use the following standards (use first that has an appropriate entry):
  • (full or abbreviated forms of) the CF Conventions' Standard Names at http://cfconventions.org/standard-names.html (gives name, description, units, contains mostly biogeochemophysical quantities)
  • the IAM community's naming standard (https://redmine.pik-potsdam.de/projects/mo/wiki/Variable_Template)
  • maybe the World Bank's "CETS codes" at https://datahelpdesk.worldbank.org/knowledgebase/articles/201175-how-does-the-world-bank-code-its-indicators (gives abbreviations for aggregate socio-economic quantities)
  • maybe use other large organizations variable "codes" or "labels" (e.g., OECD, Comtrade, UN, IWF)
  • maybe use names derived from the (lengthy) World Values Survey variable labels (see "codebook" at http://www.worldvaluessurvey.org/WVSDocumentationWV6.jsp)
  • otherwise form a new name following similar name forming conventions as the CF Conventions' Standard Names (http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html)
• naming of units: use the following standards (use first that has an appropriate entry):
  • https://github.com/SciTools/cf_units (mostly biogeochemophysical units)
  • other??

Regarding the McCabe complexity checks, we have to reduce complexity as much as possible and find new complexity thresholds.

Need to implement interpolation for step and event values in runner.

PEP257 is giving out a lot of errors, since it requires a very strict formatting of docstrings. Do we want this? One of the complaints is this:
<<First word of the docstring should not be This [pep257]>>
This might be very annoying during further coding...

Implement feature to change the number of entities by creation or annihilation (maybe also merge/split?). Where is the right place in the code for this?
@KilianZimmerer @mensch72

Change Formatting of strings from old to new style to make code more consistent:
https://pyformat.info/
@KilianZimmerer