jaff-chemistry · markkrumholz · Jul 10, 2026 · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,60 +1,79 @@
 # Contributing to JAFF
 
-Welcome! We're excited that you're interested in contributing to JAFF (Just Another Fancy Format), an astrochemical network parser.
+Thanks for your interest in contributing! This is a quick-start summary — the
+full guides live in [`docs/development/`](docs/development/) and online in the
+[Documentation](https://jaff-chemistry.github.io/jaff/).
 
-PLEASE NOTE:
-If you choose to make contributions to the code, you hereby grant a non-exclusive, royalty-free perpetual license
-to install, use, modify, prepare derivative works, incorporate into other computer software,
-distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form.
+## Ways to Contribute
 
-## Getting Started
+- **Report bugs** — open an issue with steps to reproduce.
+- **Suggest features** — open an issue to discuss before building anything large.
+- **Fix issues / add features** — pick an issue, then send a PR.
+- **Improve docs** — corrections and clarifications are always welcome.
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/jaff.git`
-3. Create a new branch: `git checkout -b your-feature-name`
-4. Install the package in development mode: `uv pip install -e ".[dev]"`
+For major changes, open an issue first so the direction can be agreed on before
+you invest time.
 
-## Development Process
+## Development Setup
 
-### Code Style
+Fork the repo, clone your fork, and install in editable mode with dev tooling:
 
-- Match the style and formatting of surrounding code
-- Keep solutions simple, clean, and maintainable
-- Each code file should start with a 2-line comment beginning with "ABOUTME: "
-- Preserve existing comments unless they are demonstrably false
+```bash
+git clone https://github.com/YOUR_USERNAME/jaff.git
+cd jaff
+pip install -e ".[dev]"
+```
 
-### Making Changes
+Requires **Python 3.11+**. Full instructions (venv, uv, conda, IDE setup) are in
+the [Installation Guide](docs/development/installation.md).
 
-1. Make the smallest reasonable changes to achieve your goal
-2. Write tests BEFORE implementing new features (Test-Driven Development)
-3. Ensure all tests pass before submitting
-4. Commit frequently with clear, descriptive messages
+## Workflow
 
-### Testing
+1. **Branch** off an up-to-date `main` — never commit to `main` directly. Prefix
+   the branch with its purpose: `feature/`, `bug-fix/`, `docs/`, `refactor/`,
+   `test/`, or `chore/`.
 
-All contributions should include:
+   ```bash
+   git checkout main && git pull upstream main
+   git checkout -b feature/short-description
+   ```
 
-- Unit tests for individual components
-- An example Python notebook in `examples/` demonstrating your feature
+2. **Commit** with clear messages explaining _what_ and _why_. Use Conventional
+   Commit types (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`):
 
-Run tests with: `uv run pytest` (once test framework is set up)
+   ```bash
+   git commit -m "feat: add support for GPU code generation"
+   ```
 
-### Submitting Changes
+3. **Check** that tests pass and code is formatted before opening a PR:
 
-1. Push your branch to your fork
-2. Create a Pull Request with:
-    - Clear description of the changes
-    - Reference to any related issues
-    - Test results showing all tests pass
-3. Address any review feedback promptly
+   ```bash
+   pytest          # run the test suite
+   ruff check .    # lint
+   ruff format .   # format
+   ```
 
-## Questions?
+4. **Open a PR** against `jaff-chemistry/jaff:main`. Summarize the change,
+   reference related issues (`Fixes #123`), and note anything reviewers should
+   look at. All CI checks (tests on Linux/macOS/Windows × Python 3.11–3.13, docs
+   build, notebook execution) must pass before merge.
 
-Open an issue for:
+## Standards
 
-- Bug reports
-- Feature requests
-- Questions about the codebase
-- Discussion of potential contributions
+- **Code style** — Ruff (90-char lines, double quotes), built-in generics and
+  `X | None` unions, NumPy-style docstrings. See the
+  [Code Style Guide](docs/development/code-style.md).
+- **Tests** — pytest, one behaviour per test, descriptive names. New code should
+  be fully covered. See the [Testing Guide](docs/development/testing.md).
+- **Codebase layout** — see the
+  [Codebase Structure](docs/development/codebase-structure.md) guide.
 
-Thank you for contributing to JAFF!
+## Getting Help
+
+- **GitHub Issues** — bug reports and feature requests.
+- **GitHub Discussions** — questions about the codebase or usage.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).
diff --git a/README.md b/README.md
@@ -1,129 +1,129 @@
 <div align="center">
-    <h1>JAFF</h1>
-    <img src="assets/logo.png" alt="Logo" width="100" /><br>
-    (Just Another Fancy Format)
-    <br><br>
+  <img src="assets/logo.png" alt="JAFF logo" width="120" />
+
+  <h1>JAFF</h1>
+
+  <p><em>Just Another Fancy Format</em></p>
+
+  <p>A fast, multi-format astrochemical network parser with analysis, code generation, and explicit photochemistry.</p>
+
+  <p>
+    <a href="https://github.com/jaff-chemistry/jaff/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-8b6cff?style=for-the-badge&labelColor=241b2f&logo=opensourceinitiative&logoColor=EDE4FF"></a>
+    <a href="https://www.python.org/downloads/"><img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-e05fb0?style=for-the-badge&labelColor=241b2f&logo=python&logoColor=EDE4FF"></a>
+    <img alt="Version" src="https://img.shields.io/badge/Version-0.1.5-ff6a5a?style=for-the-badge&labelColor=241b2f&logo=semanticrelease&logoColor=EDE4FF">
+    <img alt="Status" src="https://img.shields.io/badge/Status-alpha-ffc24b?style=for-the-badge&labelColor=241b2f&logo=rocket&logoColor=EDE4FF">
+    <a href="https://jaff-chemistry.github.io/jaff/"><img alt="Docs" src="https://img.shields.io/badge/Docs-online-8b6cff?style=for-the-badge&labelColor=241b2f&logo=readthedocs&logoColor=EDE4FF"></a>
+  </p>
+
+  <p>
+    <a href="#installation">Installation</a> ·
+    <a href="#quick-start">Quick Start</a> ·
+    <a href="#supported-network-formats">Formats</a> ·
+    <a href="https://jaff-chemistry.github.io/jaff/">Documentation</a> ·
+    <a href="#contributing">Contributing</a>
+  </p>
 </div>
 
-An astrochemical network parser that supports multiple reaction network formats including KIDA, UDFA, PRIZMO, KROME, and UCLCHEM.
+---
+
+## Overview
+
+**JAFF** is an astrochemical network parser that reads multiple network formats, validates and analyses them, generates simulation code, and handles explicit photochemistry — all from a single tool.
+
+- **Multi-format** — parse KIDA, UDFA, PRIZMO, KROME, and UCLCHEM networks
+- **Automatic validation** — catch malformed reactions and inconsistent species
+- **Analysis** — inspect species, reactions, masses, charges, and rates
+- **Code generation** — emit ODE solvers in C, C++, Python, Fortran, Rust, Julia, and R
+- **Explicit photochemistry** — first-class treatment of photoreactions
 
-For detailed instructons, please refer to the [Documentation](https://jaff-chemistry.github.io/jaff/)
+> Full guides and API reference live in the [Documentation](https://jaff-chemistry.github.io/jaff/).
 
 ## Installation
 
-### From source
+Clone the repository and install with `pip`:
 
 ```bash
 git clone https://github.com/jaff-chemistry/jaff.git
 cd jaff
 pip install .
 ```
 
-### For development
-
-```bash
-git clone https://github.com/jaff-chemistry/jaff.git
-cd jaff
-pip install -e .  # Editable install
-```
+Requires **Python 3.11+**.
 
 ## Quick Start
 
-### Command Line Usage
+### Command Line
 
-After installation, you can use the `jaff` command:
+Installation provides two commands: `jaffx` for quick network inspection and
+export, and `jaffgen` for code generation.
 
 ```bash
-# Load and validate a network file
-jaff networks/gas_reactions_kida.uva.2024.in
+# Count species and reactions in a network
+jaffx get num-species  --network networks/COthin/react_COthin.jet
+jaffx get num-reactions --network networks/COthin/react_COthin.jet
 
-# List all species and reactions
-jaff networks/test.dat --list-species --list-reactions
+# Export rate coefficients over a temperature range to a text file
+jaffx export txt --network networks/COthin/react_COthin.jet --tmin 10 --tmax 1e4
 ```
 
-### Python API Usage
+### Network Parsing
+
+The format is auto-detected — the same `Network` call reads KIDA, KROME,
+PRIZMO, UDFA, and UCLCHEM files, plus JAFF's own `.jaff` format:
 
 ```python
 from jaff import Network
 
-# Load a chemical network
-network = Network("networks/react_COthin")
+network = Network("networks/COthin/react_COthin.jet")
+network = Network("networks/kida_uva_2024/gas_reactions_kida.uva.2024.jet")
+```
+
+### Analysis
 
+```python
 # Access species
 for species in network.species:
     print(f"{species.name}: mass={species.mass}, charge={species.charge}")
 
 # Access reactions
 for reaction in network.reactions:
-    print(f"{reaction.get_sympy()}")
+    print(f"{reaction.reactants}")
 ```
 
-## Features
+### Code Generation
 
-- **Multi-format support**: Automatically detects and parses KIDA, UDFA, PRIZMO, KROME, and UCLCHEM formats
-- **Validation**: Checks for mass and charge conservation in reactions
-- **Species analysis**: Automatic extraction of elemental composition and properties
-- **Rate calculations**: Temperature-dependent rate coefficient evaluation
-- **ODE generation**: Creates differential equations for chemical kinetics
-
-## Supported Network Formats
-
-- **KIDA**: Kinetic Database for Astrochemistry format
-  Reference: [A&A, 689, A63 (2024)](https://doi.org/10.1051/0004-6361/202450606)
-- **UDFA**: UMIST Database for Astrochemistry format
-  Reference: [A&A, 682, A109 (2024)](https://doi.org/10.1051/0004-6361/202346908)
-- **PRIZMO**: Uses `->` separator with `VARIABLES{}` blocks
-  Reference:[MNRAS 494, 4471–4491 (2020)](https://doi.org/10.1093/mnras/staa971)
-- **KROME**: Comma-separated values with `@format:` header
-  Reference: [MNRAS 439, 2386–2419 (2014)](https://doi.org/10.1093/mnras/stu114)
-- **UCLCHEM**: Comma-separated with `,NAN,` marker (UNDER CONSTRUCTION)  
-   Reference: [J. Holdship et al 2017 AJ 154 38](https://doi.org/10.3847/1538-3881/aa773f)
+```bash
+jaffgen --template microphysics --network networks/GOW/GOW.jet
+```
 
-## Primitive Variables
+**Supported languages:** C · C++ · Python · Fortran · Rust · Julia · R
 
-The following variables are recognized in rate expressions:
+## Supported Network Formats
 
-- `tgas`: gas temperature, K
-- `av`: visual extinction, Draine units
-- `crate`: cosmic rays ionization rate of H2, 1/s
-- `ntot`: total number density, 1/cm3
-- `hnuclei`: H nuclei number density, 1/cm3
-- `d2g`: dust-to-gas mass ratio
+| Format      | Reference                                                                    |
+| ----------- | ---------------------------------------------------------------------------- |
+| **KIDA**    | [A&A, 689, A63 (2024)](https://doi.org/10.1051/0004-6361/202450606)          |
+| **UDFA**    | [A&A, 682, A109 (2024)](https://doi.org/10.1051/0004-6361/202346908)         |
+| **PRIZMO**  | [MNRAS 494, 4471–4491 (2020)](https://doi.org/10.1093/mnras/staa971)         |
+| **KROME**   | [MNRAS 439, 2386–2419 (2014)](https://doi.org/10.1093/mnras/stu114)          |
+| **UCLCHEM** | [J. Holdship et al 2017 AJ 154 38](https://doi.org/10.3847/1538-3881/aa773f) |
 
 ## Examples
 
-Example network files can be found in the `networks/` directory.
-
-## Development
-
-To contribute or modify JAFF:
-
-```bash
-# Install in development mode with dev dependencies
-pip install -e ".[dev]"
-
-# Run tests
-pytest
+Example network files can be found in the [`networks/`](networks/) directory.
 
-# Format code
-ruff format
+## Contributing
 
-# Lint code
-ruff check src/jaff
+Contributions are welcome! To contribute or modify JAFF, please refer to our
+[Contributing Guide](CONTRIBUTING.md).
 
-# Organize imports
-ruff check --select I --fix
-```
+## License
 
-## JAFF Schema Validation
-
-JAFF network exports are JSON payloads serialized to `.jaff` (optionally gzip-compressed as `.jaff.gz`).
-To validate a decompressed payload against the schema:
-
-```bash
-check-jsonschema --schemafile jaff.network.schema.json test.jaff
-```
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
 
 ---
 
-![xkcd:927](./assets/xkcd.png)
+<div align="center">
+  <img src="./assets/xkcd.png" alt="xkcd 927: Standards" width="500" /><br>
+  <sub><a href="https://xkcd.com/927/">xkcd 927</a></sub>
+</div>
diff --git a/assets/logo.png b/assets/logo.png
diff --git a/assets/logo.svg b/assets/logo.svg
diff --git a/assets/logo.webp b/assets/logo.webp
diff --git a/docs/api/codegen/codegen/get_commons.md b/docs/api/codegen/codegen/get_commons.md
@@ -22,7 +22,7 @@ const int nreactions = 5;
 **Parameters**
 
 **idx_offset** : _int, optional_
-: Base index added to each species position. `-1` uses the language default stored in `self.ioff`. Default `-1`.
+: Base index added to each species position. `-1` uses the language default stored in `self.lang.idx_offset`. Default `-1`.
 
 **idx_prefix** : _str, optional_
 : Prefix for index names, e.g. `"idx_"`. Default `""`.