Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New model documentation is outdated #588

Open
davidorme opened this issue Oct 10, 2024 · 1 comment
Open

New model documentation is outdated #588

davidorme opened this issue Oct 10, 2024 · 1 comment
Labels
bug Something isn't working

Comments

@davidorme
Copy link
Collaborator

Describe the bug

With the introduction of #388 and #548, our existing documentation on creating new model is outdated:

  1. The variable class attributes are incomplete:

The {attr}`~virtual_ecosystem.core.base_model.BaseModel.vars_required_for_init` attribute
: This is a tuple that sets which variables must be present in the data used to create a
new instance of the model. Each entry should provide a variable name and then another
tuple that sets any required axes for the variable. For example:
```python
() # no required variables
(('temperature', ()),) # temperature must be present, no core axes
(('temperature', ('spatial',)),) # temperature must be present and on the spatial axis
```
The {attr}`~virtual_ecosystem.core.base_model.BaseModel.vars_updated` attribute : This
is a tuple that provides information about which data object variables are updated by
this model. Entries should simply be variable names. The information contained here is
used to determine which variables to include in the continuous output. So, it is
important to ensure that this information is up to date.

  1. The docs refer to the old manual dependency setting rather than the new system based on the order of variable usage:

#### Model dependencies
Your model may depend on a particular execution order for other models. For example, the
`freshwater` model might rely on data set up by the `hydrology` model, and so the
`hydrology` model needs to be initialised and updated before the `freshwater` model.
This is controlled using model configuration: although these dependencies may be
strong, it is more flexible to set them up through the configuration process than by
hard coding dependencies into the model objects themselves.
Your JSON Schema document therefore needs to include the following at the root level, so
that the model configuration includes a `[freshwater.depends]` section:
```json
"depends": {
"type": "object",
"default": {},
"properties": {
"init": {
"type": "array",
"default": ["hydrology"],
"items": {
"type": "string"
}
},
"update": {
"type": "array",
"default": ["hydrology"],
"items": {
"type": "string"
}
}
}
}
```
Note that this schema provides **default dependencies**, which set which models should
run before your model. There is no guarantee that users will necessarily include all of
these models in their configuration and the dependencies can always be overridden by
users. Configurations that do this may well not work, but that is for users to tackle.

@davidorme davidorme added the bug Something isn't working label Oct 10, 2024
@davidorme davidorme added this to the Documentation system milestone Oct 10, 2024
@davidorme
Copy link
Collaborator Author

This should also handle the development of the static model system #373

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

1 participant