Installation

Quick Start

Install pixi on your machine. Clone this repository, then invoke from a terminal:

$ pixi run run_parcel examples/simple.yml

An environment should automatically be set up and the model run from it.

Normal Installation

To quickly get started with running pyrcel, complete the following steps:

  • Set up a new Python environment; we recommend using mambaforge:

$ mamba create -n pyrcel_quick_start python=3.11

  • Activate the new Python environment and install the model and its dependencies. If you install the published version from PyPi (recommended), then you also need to install Assimulo using the Mamba package manager - but no other manual dependency installation is necessary:

$ mamba activate pyrcel_quick_start
$ pip install pyrcel
$ mamba install -c conda-forge assimulo

  • Run a test simulation using the CLI tool and a sample YAML file from pyrcel/examples/*.yml (you may want to clone the repository or download them locally):

$ run_parcel simple.yml

Detailed Installation Notes

From PyPI

This package and most of its dependencies can automatically be installed by using pip:

$ pip install pyrcel

However, note that this will not install Assimulo; you will separately need to install that, using the conda/mamba package manager. See the example in the previous section for more details.

From source code

To grab and build the latest bleeding-edge version of the model, you should use pip and point it to the source code repository on github:

$ pip install git+git://github.com/darothen/pyrcel.git

The same caveats as in the previous section regarding installing Assimulo will still apply.

You can also install the code from the cloned source directory by invoking pip install from within it; this is useful if you’re updating or modifying the model, since you can install an “editable” package which points directly to the git-monitored code:

$ cd path/to/pyrcel/
$ pip install -e .

Dependencies

This code was originally written for Python 2.7, and then futurized to Python 3.3+ with hooks for backwards compatibility. It should work on modern Python versions, and we recommend using Python 3.11+ for the greatest compatibility with required dependencies.

The easiest way to manage dependencies is to use a tool like Mambaforge <https://conda-forge.org/miniforge/> to set up an environment. Suitable environment files can be found in the pyrcel/ci directory.

Necessary dependencies

All of these (except for Assimulo; see the note below) can be installed via pip:

Note

As of version 1.2.0, the model integration components are being re-written and only the CVODE interface is exposed. As such, Assimulo is a core and required dependency; in the future the other solvers will be re-enabled. You should first try to install Assimulo via conda

$ mamba install -c conda-forge assimulo

since this will automatically take care of obtaining necessary compiled dependencies like sundials. However, for best results you may want to manually install Assimulo, since the conda-forge recipe may default to a sundials/OpenBLAS combination which could degare the performance of the model.

Numerical solver dependencies

Testing

A nose test-suite is under construction. To check that your model is configured and running correctly, you copy and run the notebook corresponding to the basic run example, or run the command-line interface version of the model with the pre-packed simple run case:

$ cd path/to/pyrcel/
$ ./run_parcel examples/simple.yml

Bugs / Suggestions

The code has an issue tracker on github and I strongly encourage you to note any problems with the model there, such as typos or weird behavior and results. Furthermore, I’m looking for ways to expand and extend the model, so if there is something you might wish to see added, please note it there or send me an e-mail. The code was written in such a way that it should be trivial to add physics in a modular fashion.