UCLCHEM is a gas-grain chemical code that propagates the abundances of chemical species through a network of user-defined reactions according to the physical conditions of the gas. We provide several physical models to enable the modeling of different astrophysical environments and a utility script MakeRates to help the user produce a chemical network from simple lists of reactions and species.

License

We use the MIT License, allowing the user liberties with how they use UCLCHEM. To foster our efforts and open science, we however kindly request the user to:

1. Cite the paper if you use our code.
2. Make public any flavors of UCLCHEM you derive and use for articles, in order of preference: as a pull request on this reposistory, as a fork, code uploaded somewhere.

Installation Instructions

Full documentation is available from the website: uclchem.github.io

UCLCHEM is intended to be used as a python module but must be installed from source rather than an online index such as Pypi. This is because users are expected to modify the source code, at least by creating their own networks. To obtain and install the code simply run:

git clone https://github.com/uclchem/UCLCHEM.git
cd UCLCHEM
pip install .

You can then import uclchem in any python script. You need to pip install . whenever you change your network with Makerates.

To see the contents of this python module, check our Python API docs. To see some example notebooks, check the tutorial section of the docs or the notebooks in Tutorials/.

Prerequisites

To build UCLCHEM, you'll need gfortran, make and python 3.12+. On MacOS, make sure to have xcode installed. See more detailed installation instructions here.

Changes and releases

You can check a broad description of changes in each of the releases.

Contributing

This is an open source science code for the community and are open to pull requests. We are also happy to work with you to produce a physics module if none of the models available in the python module uclchem.model suit the modeling work you wish to do. If you are contributing, please try to work with our current code style. Feel free to checkout the latest developments with git fetch; git checkout develop We have the following general guidelines:

Editable development Setup

After cloning the repository, install the development dependencies and set up pre-commit hooks:

pip install meson-python meson ninja # dependencies 
pip install -e ".[dev]" --no-build-isolation # uclchem
pre-commit install # linting, type checking and formatting

This last command will automatically run linting and formatting checks before each commit and save you time with failed CI/CD. This might introduce some weird behavior with fortran .mod files lingering if you quit compilation at any point, so beware!

Github

• Work in a personal branch or fork to your own Github to develop features.
• Make sure you base your new work on the develop branch.
• Pull requests should be opened with the develop branch as target.
• In principle, squash and merge is preferred over keeping the entire git commit history when merging into develop.
• Releases will be coordinated by the core developers, this will constitute a push to main and creating a release.

Python

• Use Ruff to format your code.
• snake_case variables and functions with self-explanatory names
• Docstrings for all functions (verified using pymend, they're used to produce the online docs!

Fortran

• camelCase variable and subroutines names that are self-explanatory where possible
• CAPITALIZED fortran built in functions to make code structure apparent.
• Modularization, related subroutines should be added as modules. Small tweaks should be inserted into relevant module

Citing UCLCHEM

If you use UCLCHEM for your research, please cite the following paper for the framework and any important papers mentioned therin that contributed to specific modules you used.

Developers

Developer tools

After adding or renaming Fortran PARAMETER declarations, regenerate src/uclchem/advanced/fortran_metadata.yaml by running uclchem-generate-metadata (or --dry-run to preview changes). The CI workflow check-fortran-metadata.yml will fail on pull requests if the file is out of date.