RMG-Py v4.0.0 stable

.conda/conda_build_config.yaml

@@ -0,0 +1,14 @@
+# Restrict conda-build's variant matrix so the solver does not enumerate
+# python/numpy combinations from internal_defaults. The CI workflow's
+# CONDA_PY env var narrows to one of these python versions per matrix cell.
+#
+# Without this file, conda-build considers every (python, numpy) pair from
+# its internal defaults during the "Getting pinned dependencies" phase,
+# which substantially enlarges the search space the libmamba solver has
+# to traverse.
+python:
+  - 3.9
+  - 3.10
+  - 3.11
+numpy:
+  - 1.26

.conda/meta.yaml

@@ -4,173 +4,76 @@
 # RMG-Py into binaries which can then be uploaded for access via the conda package manager
 # to use this file, you can follow the procedure shown in .github/workflows/conda_build.yml
 #
+# Variant axes (python, numpy) are pinned in .conda/conda_build_config.yaml so that
+# conda-build does not enumerate every combination from its internal defaults.
+#
 package:
   name: rmg
-  version: 3.3.0
+  version: 4.0.0
 
 source:
   path: ../
 
 build:
   number: 0
   script: |
-    python utilities.py check-pydas  # write the rmgpy/solver/settings.pxi file
-    python setup.py install --single-version-externally-managed --record=record.txt
+    {{ PYTHON }} utilities.py check-pydas  # write the rmgpy/solver/settings.pxi file
+    {{ PYTHON }} setup.py install --single-version-externally-managed --record=record.txt
 
 requirements:
   build:
     - {{ compiler('c') }}
-  host:
-    - conda-forge::cairo
-    - conda-forge::cairocffi
-    - conda-forge::ffmpeg >=7
-    - conda-forge::xlrd
-    - conda-forge::xlwt
-    - conda-forge::h5py
-    - conda-forge::graphviz >=12
-    - conda-forge::markupsafe
-    - conda-forge::psutil
-    - conda-forge::ncurses
-    - conda-forge::suitesparse
-    - conda-forge::graphviz 
-    - conda-forge::pyopenssl >20
-    - conda-forge::coolprop
-    - conda-forge::cantera =2.6
-    - conda-forge::mopac
-    - conda-forge::cclib >=1.6.3,<1.9
-    - conda-forge::openbabel >=3
-    - conda-forge::rdkit >=2022.09.1
-    - conda-forge::python >=3.9
-    - conda-forge::setuptools <80
-    - conda-forge::coverage
-    - conda-forge::cython >=0.25.2,<3.1
-    - conda-forge::scikit-learn
-    - conda-forge::scipy >=1.9
-    - conda-forge::numpy >=1.10.0,<2
-    - conda-forge::pydot
-    - conda-forge::jinja2
-    - conda-forge::jupyter
-    - conda-forge::pymongo
-    - conda-forge::pyparsing
-    - conda-forge::pyyaml
-    - conda-forge::networkx
-    - conda-forge::pytest
-    - conda-forge::pytest-cov
-    - conda-forge::pytest-check
-    - conda-forge::pyutilib
-    - conda-forge::matplotlib >=1.5
-    - conda-forge::mpmath
-    - conda-forge::pandas
-    - conda-forge::gprof2dot
-    - conda-forge::numdifftools
-    - conda-forge::quantities !=0.16.0,!=0.16.1
-    - conda-forge::ringdecomposerlib-python
-    - rmg::pydas >=1.0.3
-    - rmg::pydqed >=1.0.3
-    - rmg::symmetry
-    - rmg::rmgdatabase =3.3.0
-    - blas=*=openblas
-  run:
+  host: &runtime_requirements
     - conda-forge::cairo
     - conda-forge::cairocffi
     - conda-forge::ffmpeg >=7
     - conda-forge::xlrd
     - conda-forge::xlwt
-    - conda-forge::h5py
+    - conda-forge::h5py >=3.10
     - conda-forge::graphviz >=12
     - conda-forge::markupsafe
     - conda-forge::psutil
     - conda-forge::ncurses
     - conda-forge::suitesparse
-    - conda-forge::graphviz 
-    - conda-forge::pyopenssl >20
+    - conda-forge::pyopenssl >24
     - conda-forge::coolprop
-    - conda-forge::cantera =2.6
+    - conda-forge::cantera >=3.0
     - conda-forge::mopac
     - conda-forge::cclib >=1.6.3,<1.9
     - conda-forge::openbabel >=3
-    - conda-forge::rdkit >=2022.09.1
-    - conda-forge::python >=3.9
-    - conda-forge::setuptools <80
-    - conda-forge::coverage
-    - conda-forge::cython >=0.25.2,<3.1
-    - conda-forge::scikit-learn
-    - conda-forge::scipy >=1.9
-    - conda-forge::numpy >=1.10.0,<2
+    - conda-forge::rdkit >=2024
+    # python intentionally left loose so the CI matrix (via CONDA_PY)
+    # can pin it without a contradictory-deps error. The real variant pin
+    # lives in .conda/conda_build_config.yaml.
+    - conda-forge::python >=3.9,<3.12
+    - conda-forge::setuptools >=70,<80
+    - conda-forge::cython >=3.0,<3.1
+    - conda-forge::scikit-learn >=1.3
+    - conda-forge::scipy >=1.13
+    - conda-forge::numpy >=1.24,<2
     - conda-forge::pydot
     - conda-forge::jinja2
-    - conda-forge::jupyter
     - conda-forge::pymongo
     - conda-forge::pyparsing
     - conda-forge::pyyaml
     - conda-forge::networkx
-    - conda-forge::pytest
-    - conda-forge::pytest-cov
-    - conda-forge::pytest-check
     - conda-forge::pyutilib
-    - conda-forge::matplotlib >=1.5
+    - conda-forge::matplotlib >=3.5
     - conda-forge::mpmath
-    - conda-forge::pandas
+    - conda-forge::pandas >=2
     - conda-forge::gprof2dot
     - conda-forge::numdifftools
     - conda-forge::quantities !=0.16.0,!=0.16.1
-    - conda-forge::ringdecomposerlib-python
+    - rmg::pysidt-rmg >=1.2
     - rmg::pydas >=1.0.3
     - rmg::pydqed >=1.0.3
     - rmg::symmetry
-    - rmg::rmgdatabase =3.3.0
+    - rmg::rmgdatabase =4.0.0
     - blas=*=openblas
+  run: *runtime_requirements
 test:
-  requires:
-    - conda-forge::cairo
-    - conda-forge::cairocffi
-    - conda-forge::ffmpeg >=7
-    - conda-forge::xlrd
-    - conda-forge::xlwt
-    - conda-forge::h5py
-    - conda-forge::graphviz >=12
-    - conda-forge::markupsafe
-    - conda-forge::psutil
-    - conda-forge::ncurses
-    - conda-forge::suitesparse
-    - conda-forge::graphviz 
-    - conda-forge::pyopenssl >20
-    - conda-forge::coolprop
-    - conda-forge::cantera =2.6
-    - conda-forge::mopac
-    - conda-forge::cclib >=1.6.3,<1.9
-    - conda-forge::openbabel >=3
-    - conda-forge::rdkit >=2022.09.1
-    - conda-forge::python >=3.9
-    - conda-forge::setuptools <80
-    - conda-forge::coverage
-    - conda-forge::cython >=0.25.2,<3.1
-    - conda-forge::scikit-learn
-    - conda-forge::scipy >=1.9
-    - conda-forge::numpy >=1.10.0,<2
-    - conda-forge::pydot
-    - conda-forge::jinja2
-    - conda-forge::jupyter
-    - conda-forge::pymongo
-    - conda-forge::pyparsing
-    - conda-forge::pyyaml
-    - conda-forge::networkx
-    - conda-forge::pytest
-    - conda-forge::pytest-cov
-    - conda-forge::pytest-check
-    - conda-forge::pyutilib
-    - conda-forge::matplotlib >=1.5
-    - conda-forge::mpmath
-    - conda-forge::pandas
-    - conda-forge::gprof2dot
-    - conda-forge::numdifftools
-    - conda-forge::quantities !=0.16.0,!=0.16.1
-    - conda-forge::ringdecomposerlib-python
-    - rmg::pydas >=1.0.3
-    - rmg::pydqed >=1.0.3
-    - rmg::symmetry
-    - rmg::rmgdatabase =3.3.0
-    - blas=*=openblas
+  # Keep this minimal: test commands below run import checks plus two example
+  # command-line runs, and do not invoke the pytest suite.
   source_files:
     - 'examples/rmg/superminimal'
     - 'examples/arkane/networks/n-butanol_msc'

.github/copilot-instructions.md

@@ -0,0 +1,180 @@
+# RMG-Py Copilot Instructions
+
+## Project Overview
+RMG-Py is the Reaction Mechanism Generator - an automatic chemical kinetics mechanism generator. It consists of two main components:
+- **RMG** (`rmgpy/`): Core mechanism generation engine
+- **Arkane** (`arkane/`): Statistical mechanics and transition state theory calculations
+
+## Architecture
+
+### Core Packages
+- `rmgpy/molecule/` - Molecular graph representation (`Molecule`, `Atom`, `Bond`, `Group`)
+- `rmgpy/thermo/` - Thermodynamic models (NASA, Wilhoit, ThermoData)
+- `rmgpy/kinetics/` - Rate coefficient models (Arrhenius, Chebyshev, pressure-dependent)
+- `rmgpy/solver/` - ODE solvers for reactor simulations
+- `rmgpy/rmg/` - Main RMG algorithm (`main.py`, `model.py`, `react.py`)
+- `rmgpy/data/` - Database interfaces for thermo, kinetics, transport
+
+### Key Base Classes
+- `RMGObject` (in `rmgpy/rmgobject.pyx`) - Base class providing `as_dict()`/`make_object()` for YAML serialization
+- `Graph`/`Vertex`/`Edge` (in `rmgpy/molecule/graph.pyx`) - Graph isomorphism via VF2 algorithm
+- `Species` and `Reaction` are central objects connecting molecules to thermodynamics and kinetics
+
+### Cython Architecture
+Performance-critical code uses Cython (`.pyx` files) with declaration files (`.pxd`):
+- Some `.py` files are also cythonized — they have a `.pxd` sibling and are listed in `setup.py` `ext_modules` (e.g. `rmgpy/species.py`, `rmgpy/reaction.py`, `rmgpy/quantity.py`, `rmgpy/constants.py`, and most of `rmgpy/molecule/`). The compiled `.so` is what gets imported, so edits won't take effect until rebuilt.
+- Always pair `.pyx` (or cythonized `.py`) with `.pxd` for public cdef classes/methods
+- Use `cpdef` for methods callable from both Python and Cython
+- Use `cimport` for Cython-level imports (e.g., `cimport rmgpy.constants as constants`)
+- Register new Cython modules in `setup.py` `ext_modules` list
+- Remember to re-compile (`make build`) after modifying any `.pyx`, `.pxd`, or cythonized `.py` file, or if there seem to be weird bugs in them.
+
+## Development Commands
+```bash
+make install          # First-time pip editable install + Cython build. Writes a .installed sentinel; subsequent `make install` is a no-op until `make clean`.
+make build            # Incremental in-place Cython rebuild (`setup.py build_ext --inplace`). Fast — use this after editing .pyx/.pxd/cythonized .py.
+make                  # Default target: dep check, install if needed (via sentinel), then `make build`. Safe go-to.
+make test             # Run unit tests (excludes functional/database tests)
+make test-functional  # Run functional tests
+make test-database    # Run database tests
+make test-all         # Run all tests
+make clean            # Remove .so/.pyc/.c build artifacts, the build/ dir, the .installed sentinel, and pip-uninstall the package.
+make decython         # Remove most .so files for "pure Python" debugging (keeps _statmech.so, quantity.so, and rmgpy/solver/*.so). Pure python mode is not reliably tested and might not work.
+make documentation    # Build Sphinx docs
+```
+
+## Testing Conventions
+- Tests live in `test/` mirroring `rmgpy/` and `arkane/` structure
+- Test files: `*Test.py` (e.g., `speciesTest.py`, `reactionTest.py`)
+- Test classes: `class TestClassName:` or `class ClassNameTest:`
+- Use `pytest` with fixtures (`@pytest.fixture(autouse=True)` for setup)
+- Markers: `@pytest.mark.functional`, `@pytest.mark.database`
+- Run specific tests: `pytest -k "test_name_pattern"`
+
+## Code Patterns
+
+### Molecular Representations
+```python
+from rmgpy.molecule import Molecule
+mol = Molecule().from_smiles("CC")  # From SMILES
+mol = Molecule().from_adjacency_list("""...""")  # From adjacency list
+mol.is_isomorphic(other_mol)  # Graph isomorphism check
+```
+
+### Species and Reactions
+```python
+from rmgpy.species import Species
+species = Species(label='ethane', molecule=[Molecule().from_smiles("CC")])
+species.generate_resonance_structures()
+```
+
+```python
+from rmgpy.reaction import Reaction
+from rmgpy.kinetics import Arrhenius
+
+# Reaction with Arrhenius kinetics
+rxn = Reaction(
+    reactants=[Species(label='CH3', molecule=[Molecule(smiles='[CH3]')]),
+               Species(label='O2', molecule=[Molecule(smiles='[O][O]')])],
+    products=[Species(label='CH3OO', molecule=[Molecule(smiles='CO[O]')])],
+    kinetics=Arrhenius(A=(2.65e12, 'cm^3/(mol*s)'), n=0.0, Ea=(0.0, 'kJ/mol'), T0=(1, 'K')),
+)
+
+# Reaction without kinetics (e.g. for isomorphism checks)
+rxn2 = Reaction(
+    reactants=[Species().from_smiles('[O]'), Species().from_smiles('O=S=O')],
+    products=[Species().from_smiles('O=S(=O)=O')],
+)
+```
+
+
+## Input Files
+- RMG inputs: Python scripts defining `database()`, `species()`, `simpleReactor()`, etc.
+- See `examples/rmg/minimal/input.py` for structure and `examples/rmg/commented/input.py` for a file with detailed comments
+- Arkane inputs: Python scripts with `species()`, `transitionState()`, `reaction()` blocks
+- See `examples/arkane/` for examples
+
+## RMG-database Integration
+The **RMG-database** is a separate repository containing all thermodynamic, kinetics, and transport data. It's typically cloned alongside RMG-Py in a sibling folder named `RMG-database`.
+
+### Database Structure (in RMG-database `input/` directory, eg. `RMG-database/input/thermo/`)
+- `thermo/` - Thermodynamic libraries and group additivity data
+- `kinetics/families/` - Reaction family templates with rate rules (e.g., `H_Abstraction`, `R_Addition_MultipleBond`)
+- `kinetics/libraries/` - Curated rate coefficient libraries
+- `solvation/` - Solvent and solute parameters
+- `transport/` - Transport properties
+
+### How RMG-Py Loads the Database
+The `RMGDatabase` class (`rmgpy/data/rmg.py`) is the central interface:
+```python
+from rmgpy.data.rmg import RMGDatabase
+database = RMGDatabase()
+database.load(
+    path='/path/to/RMG-database/input',
+    thermo_libraries=['primaryThermoLibrary'],
+    kinetics_families='default',
+    reaction_libraries=[],
+)
+```
+
+### Key Database Classes
+- `ThermoDatabase` (`rmgpy/data/thermo.py`) - Estimates thermo via group additivity or libraries
+- `KineticsDatabase` (`rmgpy/data/kinetics/database.py`) - Manages reaction families and libraries
+- `KineticsFamily` (`rmgpy/data/kinetics/family.py`) - Template-based reaction generation using `Group` pattern matching
+- `Entry` (`rmgpy/data/base.py`) - Base class for database entries with metadata
+
+### Data Flow for Species Thermodynamics
+1. `Species.get_thermo_data()` → `rmgpy.thermo.thermoengine.submit(species)`
+2. `thermoengine.submit()` generates resonance structures, then dispatches to `ThermoDatabase.get_thermo_data(species)`
+3. `ThermoDatabase` first checks thermo libraries for an exact match (via graph isomorphism)
+4. If no library match is found, `ThermoDatabase` falls back to group additivity estimation using functional group contributions
+5. The resolved result is returned as a `ThermoData`, `NASA`, or `Wilhoit` object
+
+
+### Data Flow for Reaction Kinetics
+1. `KineticsFamily.generate_reactions(reactants)` - Matches reactant molecules to family templates
+2. Creates `TemplateReaction` objects with labeled atoms from template matching
+3. `KineticsFamily.get_kinetics()` - Estimates rate using rate rules or training reactions
+4. Returns `Arrhenius` or pressure-dependent kinetics model
+
+## External Dependencies
+- **RMG-database**: In CI, `RMG_DATABASE_BRANCH` controls which RMG-database branch is cloned. Locally, the database location is set via `settings['database.directory']` (default `../RMG-database/input`) or `database.directory` in an `rmgrc` file; you may also pass an explicit path to `database.load()`.
+- **Julia/RMS**: Optional (recommended) reactor simulation backend (install via `./install_rms.sh`)
+- Environment managed via `environment.yml` (conda/mamba)
+
+## Documentation
+Documentation lives in `documentation/source/` and is built with Sphinx (`make documentation`).
+
+### User Documentation (`documentation/source/users/`)
+- `users/rmg/` - RMG user guide (how to run, configure, interpret output)
+- `users/arkane/` - Arkane user guide
+- **Critical file**: `users/rmg/input.rst` - Documents all input file options. **Must be updated when changing input file syntax or adding new features.**
+
+### API Reference (`documentation/source/reference/`)
+- Auto-generated from docstrings using `sphinx.ext.autodoc`
+- Each module has a corresponding `.rst` file (e.g., `documentation/source/reference/species/index.rst` → `rmgpy/species.py`)
+- **Maintenance**: Add new modules to the appropriate `index.rst` toctree. Docstrings in code are automatically extracted.
+- Uses reStructuredText format with `.. automodule::` directives
+
+### When to Update Documentation
+- **New input file options**: Update `documentation/source/users/rmg/input.rst`
+- **New public API**: Ensure docstrings exist; add module to `documentation/source/reference/` if new
+- **Changed behavior**: Update relevant user guide section
+- **New features**: Add to `documentation/source/users/rmg/features.rst` or create and link to new `.rst` file
+
+## Pull Request Review Guidance
+### Review Priorities
+- Verify changed behavior is covered by tests, or request targeted tests for uncovered paths.
+- Check that user-facing changes include required documentation updates (especially input syntax in `documentation/source/users/rmg/input.rst`).
+- Confirm Cython changes are complete (`.pyx`/`.pxd` parity, required setup wiring, and likely rebuild impact).
+- Watch for performance regressions in hot paths (`rmgpy/molecule/`, `rmgpy/solver/`, kinetics generation loops).
+
+### Other checks
+- If `environment.yml` or `.conda/meta.yaml` change, verify they are consistent.
+- For changes that affect data loading or estimators, verify assumptions against RMG-database integration points in `rmgpy/data/rmg.py` and related loaders.
+
+## Style Guidelines
+- Follow PEP 8 for new or modified code, but don't modify code just to fix style
+- Docstrings describe purpose, not implementation
+- Use `logging` module (not print statements)
+- MIT license header required on all source files