Merge pull request #166 from ReactionMechanismGenerator/readme

Readme

Author: alongd

.github/workflows/ci.yml

@@ -87,7 +87,8 @@ jobs:
           cache-environment: true
           generate-run-shell: false
           create-args: >-
-            --channel-priority flexible
+            python=3.11
+            --channel-priority strict
 
       # 8. Compile RMG-Py (Cython extensions, in rmg_env)
       - name: Compile RMG-Py

README.md

@@ -3,32 +3,148 @@
 </p>
 
 # The Tandem Tool (T3) for automated chemical kinetic model development
-[![Docker Image Build and Push](https://github.com/ReactionMechanismGenerator/T3/actions/workflows/docker_build.yml/badge.svg?branch=main)](https://github.com/ReactionMechanismGenerator/T3/actions/workflows/docker_build.yml)
-![Release](https://img.shields.io/badge/version-0.1.0-blue.svg)
-![Build Status](https://github.com/ReactionMechanismGenerator/T3/actions/workflows/cont_int.yml/badge.svg)
+
+[![CI](https://github.com/ReactionMechanismGenerator/T3/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ReactionMechanismGenerator/T3/actions/workflows/ci.yml)
+[![Docs](https://github.com/ReactionMechanismGenerator/T3/actions/workflows/gh-pages.yml/badge.svg)](https://reactionmechanismgenerator.github.io/T3/)
 [![codecov](https://codecov.io/gh/ReactionMechanismGenerator/T3/branch/main/graph/badge.svg)](https://codecov.io/gh/ReactionMechanismGenerator/T3)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
 ![python](https://img.shields.io/badge/Python-3.12+-blue.svg)
 
-T3 iteratively generates and refines detailed chemical kinetic models by combining
+**T3** automates the development of detailed chemical kinetic models.
+Given a set of initial species and conditions, it produces a validated model with
+high-fidelity thermochemistry and rate parameters by iteratively combining
 [RMG](https://rmg.mit.edu/) for model generation,
 [Cantera](https://cantera.org/) for sensitivity analysis,
 and [ARC](https://reactionmechanismgenerator.github.io/ARC/) for quantum mechanical calculations.
 
-### T3 works according to the following general scheme:
-
 ![T3 scheme][cycle]
 
 [cycle]: /grf/T3-circle.gif "T3 scheme"
 
+---
+
+## Features
+
+- **Iterative refinement:** runs RMG, identifies sensitive species and reactions via SA, computes
+  accurate thermo/kinetics with ARC, and feeds the results back into the next iteration
+- **Multiple SA adapters:** constant TP/HP/UV, PFR, JSR, and brute-force ignition delay time (IDT)
+- **Equivalence-ratio sweeps:** fuel/oxidizer/diluent role taxonomy with automatic concentration
+  computation across a grid of temperatures, pressures, and equivalence ratios
+- **Uncertainty analysis:** local and global UA via polynomial chaos expansion
+- **Restart support:** T3 can resume from any interrupted iteration
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12+
+- [Conda](https://docs.conda.io/en/latest/) (we recommend [Miniforge](https://github.com/conda-forge/miniforge))
+
 ### Quick start
 
 ```bash
 git clone https://github.com/ReactionMechanismGenerator/T3.git
 cd T3
-make install all
+make install
+conda activate t3_env
+```
+
+This clones and installs ARC, RMG-Py, RMG-database, and all external dependencies.
+See the [full installation guide](https://reactionmechanismgenerator.github.io/T3/installation/)
+for manual installation and troubleshooting.
+
+---
+
+## Usage
+
+Create a YAML input file and run T3:
+
+```bash
 conda activate t3_env
+python T3.py input.yml
 ```
 
-See the [full documentation](https://reactionmechanismgenerator.github.io/T3/) for
-detailed installation instructions, tutorials, and examples.
+A minimal input file looks like:
+
+```yaml
+project: my_project
+
+t3:
+  options:
+    max_T3_iterations: 10
+  sensitivity:
+    adapter: CanteraConstantTP
+    top_SA_species: 10
+    top_SA_reactions: 10
+
+rmg:
+  database:
+    thermo_libraries: ['primaryThermoLibrary', 'BurkeH2O2']
+    kinetics_libraries: ['primaryH2O2']
+  species:
+    - label: H2
+      smiles: '[H][H]'
+      concentration: 0.67
+    - label: O2
+      smiles: '[O][O]'
+      concentration: 0.33
+    - label: OH
+      smiles: '[OH]'
+      SA_observable: true
+  reactors:
+    - type: gas batch constant T P
+      T: 1000
+      P: 1
+      termination_conversion:
+        H2: 0.9
+      termination_time: [5, 's']
+  model:
+    core_tolerance: [0.05, 0.01]
+
+qm:
+  adapter: ARC
+  level_of_theory: CBS-QB3
+```
+
+See the [input reference](https://reactionmechanismgenerator.github.io/T3/input_reference/)
+for all available options.
+
+---
+
+## Documentation
+
+See the [full documentation](https://reactionmechanismgenerator.github.io/T3/) for:
+
+- [Installation](https://reactionmechanismgenerator.github.io/T3/installation/)
+- [Running T3](https://reactionmechanismgenerator.github.io/T3/running/)
+- [Tutorials](https://reactionmechanismgenerator.github.io/T3/tutorials/1_no_qm/)
+- [Input reference](https://reactionmechanismgenerator.github.io/T3/input_reference/)
+- [Examples](https://reactionmechanismgenerator.github.io/T3/examples/)
+
+---
+
+## Development
+
+```bash
+make test            # Run tests with coverage
+make test-main       # Run main unit tests only
+make test-functional # Run functional (integration) tests
+```
+
+---
+
+## Contributing
+
+We welcome contributions!
+
+- Found a bug or have a feature request? [Open an issue](https://github.com/ReactionMechanismGenerator/T3/issues)
+- See the [contributing guide](https://reactionmechanismgenerator.github.io/T3/contribute/) to get started
+
+---
+
+## License
+
+T3 is released under the [MIT License](https://github.com/ReactionMechanismGenerator/T3/blob/main/LICENSE).

devtools/install_all.sh

@@ -79,6 +79,15 @@ make
 
 conda deactivate
 
+# Create or update t3_env
+cd ..
+cd T3 || { echo "Cannot find T3 directory"; exit 1; }
+if { $COMMAND_PKG env list | grep 't3_env'; } >/dev/null 2>&1; then
+    $COMMAND_PKG env update -n t3_env -f environment.yml
+else
+    $COMMAND_PKG env create -f environment.yml
+fi;
+
 # Switch to t3_env and clone/install ARC
 if [ "$COMMAND_PKG" == "micromamba" ]; then
     micromamba activate t3_env

environment.yml

@@ -2,45 +2,44 @@ name: t3_env
 
 channels:
   - conda-forge
-  - anaconda
 
 dependencies:
   # ─── core ─────────────────────────────────────
-  - conda-forge::python >=3.12.*
-  - conda-forge::numpy  >=2.1.*
-  - conda-forge::pip
+  - python >=3.12
+  - numpy >=2.1
+  - pip
 
   # ─── conda-forge packages ─────────────────────
-  - conda-forge::ase >=3.22.1
-  - conda-forge::cairo
-  - conda-forge::cairocffi
-  - conda-forge::cmake
-  - conda-forge::coverage
-  - conda-forge::cython >=3.0
-  - conda-forge::graphviz
-  - conda-forge::ipython
-  - conda-forge::jupyter
-  - conda-forge::lpsolve55
-  - conda-forge::mako
-  - conda-forge::matplotlib
-  - conda-forge::networkx
-  - conda-forge::openbabel >=3
-  - conda-forge::pandas
-  - conda-forge::paramiko >=2.6.0
-  - conda-forge::py3dmol >=0.8.0
-  - conda-forge::pydot
-  - conda-forge::pytables
-  - conda-forge::pytest
-  - conda-forge::pytest-cov
-  - conda-forge::pyyaml
-  - conda-forge::rdkit >=2025.03
-  - conda-forge::scipy
-  - conda-forge::sphinx
-  - conda-forge::sphinx_rtd_theme
-  - conda-forge::sphinxcontrib-jsmath
+  - ase >=3.22.1
+  - cairo
+  - cairocffi
+  - cmake
+  - coverage
+  - cython >=3.0
+  - graphviz
+  - ipython
+  - jupyter
+  - lpsolve55
+  - mako
+  - matplotlib
+  - networkx
+  - openbabel >=3
+  - pandas
+  - paramiko >=2.6.0
+  - py3dmol >=0.8.0
+  - pydantic
+  - pydot
+  - pytables
+  - pytest
+  - pytest-cov
+  - pyyaml
+  - rdkit >=2025.03
+  - scipy
+  - sphinx
+  - sphinx_rtd_theme
+  - sphinxcontrib-jsmath
 
   # ─── T3 specific packages (not in ARC) ─────────
-  - conda-forge::cantera >=3.2.0
+  - cantera >=3.2.0
   - mkdocs-material >=5.1.7
   - mkdocs-material-extensions
-  - anaconda::pydantic

mkdocs.yml

@@ -44,11 +44,6 @@ extra:
     - icon: fontawesome/brands/linkedin
       link: https://www.linkedin.com/in/alongd/
 
-# Google Analytics
-google_analytics:
-  - UA-16019208-2
-  - auto
-
 # Build hooks
 hooks:
   - docs/hooks.py