# secquoia/chemoperator architecture

> Architecture diagram of the GitHub repository secquoia/chemoperator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/secquoia/chemoperator
- Repository: https://github.com/secquoia/chemoperator

## Overview

ChemOperator’s main workflow samples reactor parameters, runs a simulator to produce a SimulationRecord, writes split HDF5 datasets, then reads and preprocesses them for neural-operator models and experiments. The graph preserves the distinct reactor families and the documented PhysicsNeMo flow capability. Source excerpts are partial, so links between unsampled subsystems are included only where the README documents the workflow or capabilities.

Main entry points: [`src/chem_operator/_datasets/generation.py`](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/generation.py) (Split generator), [`src/chem_operator/_dataset_processing/processor.py`](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_dataset_processing/processor.py) (Tensor processing), [`src/chem_operator/_experiments/workflow.py`](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/workflow.py) (Experiment workflow), [`src/chem_operator/_datasets/hdf5.py`](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/hdf5.py) (Split HDF5)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation"]
  node_sampling["Parameter sampling<br/>[sampling.py]"]
  node_cstr["CSTR simulators"]
  node_pfr["PFR simulators"]
  node_packedbed["Packed-bed simulator"]
  node_pipe["Pipe-flow simulators"]
  node_transientpipe["Transient pipe flow"]
  node_pfrheat["Heated PFR"]
  node_q2d["Quasi-2D reactor"]
end

subgraph group_data["Dataset pipeline"]
  node_generator["Split generator<br/>[generation.py]"]
  node_hdf5[("Split HDF5<br/>[hdf5.py]")]
  node_dataset["Lazy dataset<br/>[operator.py]"]
  node_inspection["Dataset inspection<br/>[inspection.py]"]
end

subgraph group_learning["Model preparation"]
  node_processor["Tensor processing<br/>[processor.py]"]
  node_packing["Field packing<br/>[packing.py]"]
  node_normalization["Normalization<br/>[base.py]"]
  node_adapters["Model adapters<br/>[adapters.py]"]
  node_deepxde["DeepXDE adapter<br/>[deepxde.py]"]
  node_models["Operator models"]
end

subgraph group_experiments["Experiments and outputs"]
  node_workflow["Experiment workflow<br/>[workflow.py]"]
  node_trainers["Model trainers<br/>[trainers.py]"]
  node_artifacts["Artifacts and metrics<br/>[artifacts.py]"]
  node_plotting["Artifact plotting<br/>[plotting.py]"]
end

subgraph group_physicsnemo["PhysicsNeMo flow"]
  node_physicsnemo["Flow PDE definitions"]
end

node_researcher(("Researcher"))
node_cantera["Cantera"]
node_q2dsolver["Q2D solver<br/>[main.cpp]"]

node_researcher -->|"requests generation"| node_generator
node_generator -->|"samples parameters"| node_sampling
node_generator -->|"runs cases"| node_cstr
node_generator -->|"runs cases"| node_pfr
node_generator -->|"runs cases"| node_packedbed
node_generator -->|"runs cases"| node_pipe
node_generator -->|"runs cases"| node_transientpipe
node_generator -->|"runs cases"| node_pfrheat
node_generator -->|"runs cases"| node_q2d
node_cstr -->|"solves with"| node_cantera
node_pfr -->|"solves with"| node_cantera
node_packedbed -->|"uses kinetics"| node_cantera
node_q2d -.->|"invokes optionally"| node_q2dsolver
node_generator -->|"writes splits"| node_hdf5
node_dataset -->|"reads cases"| node_hdf5
node_inspection -->|"inspects files"| node_hdf5
node_dataset -->|"provides samples"| node_processor
node_processor -->|"packs fields"| node_packing
node_processor -->|"normalizes fields"| node_normalization
node_processor -->|"prepares tensors"| node_adapters
node_processor -->|"adapts samples"| node_deepxde
node_adapters -->|"formats inputs"| node_models
node_researcher -->|"starts experiment"| node_workflow
node_workflow -->|"dispatches training"| node_trainers
node_workflow -->|"records outputs"| node_artifacts
node_artifacts -->|"supplies artifacts"| node_plotting
node_physicsnemo -->|"defines flow PDEs"| node_researcher

click node_sampling "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/sampling.py"
click node_cstr "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/cstr/dataset_generator.py"
click node_pfr "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pfr/dataset_generator.py"
click node_packedbed "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/packed_bed_1D/dataset_generator.py"
click node_pipe "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pipe_flow/dataset_generator.py"
click node_transientpipe "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pipe_flow_transient/dataset_generator.py"
click node_pfrheat "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pfr_heat/dataset_generator.py"
click node_q2d "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/q2d/dataset_generator.py"
click node_q2dsolver "https://github.com/secquoia/chemoperator/blob/main/Quasi-2D-packbed-experiement/external/Quasi-2D-packbed/compile/main.cpp"
click node_generator "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/generation.py"
click node_hdf5 "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/hdf5.py"
click node_dataset "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/operator.py"
click node_inspection "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/inspection.py"
click node_processor "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_dataset_processing/processor.py"
click node_packing "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_dataset_processing/packing.py"
click node_normalization "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_normalization/base.py"
click node_adapters "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_models/adapters.py"
click node_deepxde "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_models/deepxde.py"
click node_models "https://github.com/secquoia/chemoperator/tree/main/src/chem_operator/_models"
click node_workflow "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/workflow.py"
click node_trainers "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/trainers.py"
click node_artifacts "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/artifacts.py"
click node_plotting "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/plotting.py"
click node_physicsnemo "https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pipe_flow_transient/dataset_generator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sampling,node_cstr,node_pfr,node_packedbed,node_pipe,node_transientpipe,node_pfrheat,node_q2d toneBlue
class node_generator,node_hdf5,node_dataset,node_inspection toneAmber
class node_processor,node_packing,node_normalization,node_adapters,node_deepxde,node_models toneMint
class node_workflow,node_trainers,node_artifacts,node_plotting toneRose
class node_physicsnemo,node_researcher,node_cantera toneIndigo
class node_q2dsolver toneTeal
```

## Components

### Simulation

- [Parameter sampling](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/sampling.py): `src/chem_operator/sampling.py`
- [CSTR simulators](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/cstr/dataset_generator.py): `src/chem_operator/reactors/cstr/dataset_generator.py`
- [PFR simulators](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pfr/dataset_generator.py): `src/chem_operator/reactors/pfr/dataset_generator.py`
- [Packed-bed simulator](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/packed_bed_1D/dataset_generator.py): `src/chem_operator/reactors/packed_bed_1D/dataset_generator.py`
- [Pipe-flow simulators](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pipe_flow/dataset_generator.py): `src/chem_operator/reactors/pipe_flow/dataset_generator.py`
- [Transient pipe flow](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pipe_flow_transient/dataset_generator.py): `src/chem_operator/reactors/pipe_flow_transient/dataset_generator.py`
- [Heated PFR](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pfr_heat/dataset_generator.py): `src/chem_operator/reactors/pfr_heat/dataset_generator.py`
- [Quasi-2D reactor](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/q2d/dataset_generator.py): `src/chem_operator/reactors/q2d/dataset_generator.py`

### Dataset pipeline

- [Split generator](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/generation.py): `src/chem_operator/_datasets/generation.py`
- [Split HDF5](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/hdf5.py): `src/chem_operator/_datasets/hdf5.py`
- [Lazy dataset](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/operator.py): `src/chem_operator/_datasets/operator.py`
- [Dataset inspection](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_datasets/inspection.py): `src/chem_operator/_datasets/inspection.py`

### Model preparation

- [Tensor processing](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_dataset_processing/processor.py): `src/chem_operator/_dataset_processing/processor.py`
- [Field packing](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_dataset_processing/packing.py): `src/chem_operator/_dataset_processing/packing.py`
- [Normalization](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_normalization/base.py): `src/chem_operator/_normalization/base.py`
- [Model adapters](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_models/adapters.py): `src/chem_operator/_models/adapters.py`
- [DeepXDE adapter](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_models/deepxde.py): `src/chem_operator/_models/deepxde.py`
- [Operator models](https://github.com/secquoia/chemoperator/tree/main/src/chem_operator/_models): `src/chem_operator/_models`

### Experiments and outputs

- [Experiment workflow](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/workflow.py): `src/chem_operator/_experiments/workflow.py`
- [Model trainers](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/trainers.py): `src/chem_operator/_experiments/trainers.py`
- [Artifacts and metrics](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/_experiments/artifacts.py): `src/chem_operator/_experiments/artifacts.py`
- [Artifact plotting](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/plotting.py): `src/chem_operator/plotting.py`

### PhysicsNeMo flow

- [Flow PDE definitions](https://github.com/secquoia/chemoperator/blob/main/src/chem_operator/reactors/pipe_flow_transient/dataset_generator.py): `src/chem_operator/reactors/pipe_flow_transient/dataset_generator.py`

### Other components

- **Researcher**
- **Cantera**
- [Q2D solver](https://github.com/secquoia/chemoperator/blob/main/Quasi-2D-packbed-experiement/external/Quasi-2D-packbed/compile/main.cpp): `Quasi-2D-packbed-experiement/external/Quasi-2D-packbed/compile/main.cpp`

## Connections

- Researcher → Split generator: requests generation
- Split generator → Parameter sampling: samples parameters
- Split generator → CSTR simulators: runs cases
- Split generator → PFR simulators: runs cases
- Split generator → Packed-bed simulator: runs cases
- Split generator → Pipe-flow simulators: runs cases
- Split generator → Transient pipe flow: runs cases
- Split generator → Heated PFR: runs cases
- Split generator → Quasi-2D reactor: runs cases
- CSTR simulators → Cantera: solves with
- PFR simulators → Cantera: solves with
- Packed-bed simulator → Cantera: uses kinetics
- Quasi-2D reactor → Q2D solver: invokes optionally
- Split generator → Split HDF5: writes splits
- Lazy dataset → Split HDF5: reads cases
- Dataset inspection → Split HDF5: inspects files
- Lazy dataset → Tensor processing: provides samples
- Tensor processing → Field packing: packs fields
- Tensor processing → Normalization: normalizes fields
- Tensor processing → Model adapters: prepares tensors
- Tensor processing → DeepXDE adapter: adapts samples
- Model adapters → Operator models: formats inputs
- Researcher → Experiment workflow: starts experiment
- Experiment workflow → Model trainers: dispatches training
- Experiment workflow → Artifacts and metrics: records outputs
- Artifacts and metrics → Artifact plotting: supplies artifacts
- Flow PDE definitions → Researcher: defines flow PDEs