Metadata-Version: 2.4
Name: fwl-vulcan
Version: 26.10.14
Summary: Photochemical kinetics for exoplanetary atmospheres, a fast and easy-to-use python code.
Author-email: Shang-Min Tsai <shangmin.tsai@ucr.edu>, Harrison Nicholls <harrison.nicholls@ast.cam.ac.uk>
License: GPL-3.0-only
Project-URL: homepage, https://github.com/FormingWorlds/VULCAN/
Project-URL: issues, https://github.com/FormingWorlds/VULCAN/issues
Project-URL: changelog, https://github.com/FormingWorlds/VULCAN/releases
Keywords: Astronomy,Exoplanets,Model-coupling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: juliacall
Requires-Dist: matplotlib
Requires-Dist: netCDF4
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: sympy
Requires-Dist: astropy
Provides-Extra: docs
Requires-Dist: zensical; extra == "docs"
Requires-Dist: markdown-include; extra == "docs"
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Requires-Dist: mkdocstrings; extra == "docs"
Requires-Dist: mkdocs-bibtex; extra == "docs"
Provides-Extra: develop
Requires-Dist: coverage; extra == "develop"
Requires-Dist: tomlkit>=0.11.0; extra == "develop"
Requires-Dist: pytest>=8.1; extra == "develop"
Requires-Dist: pytest-cov; extra == "develop"
Requires-Dist: pytest-timeout; extra == "develop"
Requires-Dist: ruff; extra == "develop"
Requires-Dist: pre-commit; extra == "develop"
Dynamic: license-file

# VULCAN

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Tests](https://img.shields.io/github/actions/workflow/status/FormingWorlds/VULCAN/tests.yaml?branch=main&label=Tests)](https://github.com/FormingWorlds/VULCAN/actions/workflows/tests.yaml)
[![Coverage](https://gist.githubusercontent.com/nichollsh/59f094e7d22cd6af9a1cb3ea665b4260/raw/covbadge.svg)](https://github.com/FormingWorlds/VULCAN/actions/workflows/tests.yaml)
[![Docs](https://img.shields.io/website?url=https%3A%2F%2Fproteus-framework.org%2FVULCAN%2F&label=Docs&up_message=online&down_message=offline)](https://proteus-framework.org/VULCAN/)

Photochemical and thermochemical kinetics for (exo)planetary atmospheres; a fast,
open-source 1D chemical kinetics code. This distribution of VULCAN contains a number of
performance and usability improvements, and is integrated into the
[PROTEUS framework](https://proteus-framework.org/).

![Running with realtime plotting](docs/assets/demo.gif)

Full documentation: [proteus-framework.org/VULCAN](https://proteus-framework.org/VULCAN/). When contributing to this repository, please consult the [contributing guide](https://proteus-framework.org/VULCAN/Community/CONTRIBUTING.html).

Theory papers:
* [Tsai et al. 2021](https://arxiv.org/abs/2108.01790) (with photochemistry)
* [Tsai et al. 2017](https://arxiv.org/abs/1607.00409) (without photochemistry)

## Quick start

```sh
pip install -U -e .
cd fastchem_vulcan && make && cd ..
python run_vulcan.py
```

This installs VULCAN, compiles FastChem (used for equilibrium initialization), and runs
the default model (the hot Jupiter HD 189733b) with live plotting. It takes a few
minutes; results are written to `output/` as NetCDF, Pickle, and Plain Text files.

Settings for running VULCAN via the terminal are defined by `src/vulcan/config.py`.

For example, weaker vertical mixing:

```python
self.Kzz_prof  = 'const'
self.const_Kzz = 1.e7   # cm^2/s
```

or a carbon-rich (C/O = 1) atmosphere:

```python
self.use_solar = False
self.O_H = 5.37e-4
self.C_H = 5.37e-4
```

Pass `-n` to skip regenerating the chemistry from the network (only valid if you haven't edited it).

## Plotting results

```sh
cd tools/
python plot_vulcan.py <output.pkl> <species> <plot_name> [-h]
```

Reads a pickled output (e.g. `output/example.pkl`, written when `save_type` includes `'pickle'`) and plots mixing-ratio profiles for the given comma-separated species (no spaces). Plots against pressure by default, or height with `-h`.
