User Manual
Main structure of the package
The package offers several different components that can be used separately or together:
- Hierarchical input/output using
storage
: The module provides an abstract interface for writing and reading data using an hierarchical organization. Storages are conveniently created by
open_storage()
, which returns a storage object that offers a dict-like interface.- Defining parameters using
parameters
: The module provides the
Parameter
class, describing a single parameter. This can be used together with the mixinParameterized
, which allows to equip classes with default parameters and some convenience methods.- Defining models using
model
: Models are augmented functions, which define input, calculations, and output. Models can be conveniently created by decorating a function or by subclassing
ModelBase
, which is built on the parameter classes.- Model results are captured by
results
: Results are returned as the special
Result
, which keeps track of the input parameters and the data calculated by the model.ResultCollection
describes a collections of the same model evoked with different parameter values.- Submitting models to HPC using
run
: A single model can be submitted to a compute node using
submit_job()
, e.g., to run the computation on a high performance compute cluster. A parameter study using multiple jobs can be conveniently submitted usingsubmit_jobs()
. The results written to one directory can then be conveniently analyzed usingfrom_folder()
.
Design philosophy
The main requirements for the package can be summarized as follows:
Usability: The user should not need to think about how data is stored in different files. The
Result
class should simply work.Flexibility:
storage
should provide a unified interface to write data in multiple file formats (JSON, YAML, HDF, zarr, …)Stability: Future versions of the package should be able to read older files even when the internal definitions of file formats change
Modularity: Different parts of the package (like
storage
,parameters
, andrun
) should be rather independent of each other, so they can be used in isolationExtensibility: Models inherting from
ModelBase
should be easy to subclass to implement more complicated requirements (e.g., additional parameters)Self-explainability: The files should in principle contain all information to reconstruct the data, even if the
modelrunner
package is no longer available.Efficiency: The files should only store necessary information.
The last point results in particular constraints if we want to store temporal simulation results.
In most cases, there are are some data that are kept fixed for the simulation (describing physical parameters) and others that evolve with time.
We denote by attributes the parameters that are kept fixed and by data the data that varies over time.
The trajectory
module deals with such data.