# cidetec-energy-storage/cidemod architecture

> Architecture diagram of the GitHub repository cidetec-energy-storage/cidemod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cidetec-energy-storage/cidemod
- Repository: https://github.com/cidetec-energy-storage/cidemod

## Overview

cideMOD is a finite-element battery-cell simulation package implementing pseudo-X-dimensional electrochemical models, with optional thermal and degradation physics, configurable cell geometry and simulation conditions. The principal workflow configures a cell and model, builds the problem and mesh, assembles and solves the coupled equations over time, and exposes simulation results. The README documents the main physics capabilities; sampled excerpts and the source index support the core wiring. Several subsystem internals were not sampled, so links to them are limited to documented capabilities or omitted where call ownership is unclear.

Main entry points: [`src/cideMOD/main.py`](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/main.py) (Problem runtime), [`src/cideMOD/models/PXD/base_model.py`](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/PXD/base_model.py) (PXD model base), [`src/cideMOD/numerics/fem_handler.py`](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/fem_handler.py) (FEM handler), [`src/cideMOD/cell/parser.py`](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/parser.py) (Cell parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Simulation interface"]
  node_api["Battery system API<br/>[battery_system.py]"]
  node_inputs["Run inputs<br/>[inputs.py]"]
  node_problem["Problem runtime<br/>[main.py]"]
  node_plot["Result plotting<br/>[plotview.py]"]
end

subgraph group_cellmesh["Cell and geometry"]
  node_cellparser["Cell parser<br/>[parser.py]"]
  node_components["Cell components<br/>[components.py]"]
  node_parameters["Cell parameters<br/>[parameters.py]"]
  node_dimensions["Dimensional analysis"]
  node_warehouse[("State warehouse<br/>[warehouse.py]")]
  node_mesh["Mesh construction<br/>[base_mesher.py]"]
  node_gmsh["Gmsh generation<br/>[gmsh_generator.py]"]
end

subgraph group_physics["Battery physics"]
  node_registry["Model registry<br/>[__init__.py]"]
  node_modelhandler["Model handler<br/>[model_handler.py]"]
  node_pxd["PXD model base<br/>[base_model.py]"]
  node_electrochem["Electrochemistry"]
  node_thermal["Thermal model"]
  node_degradation["Degradation models"]
  node_particles["Particle models"]
end

subgraph group_numerics["Numerical runtime"]
  node_fem["FEM handler<br/>[fem_handler.py]"]
  node_timescheme["Time schemes<br/>[time_scheme.py]"]
  node_solver["Nonlinear solver<br/>[solver.py]"]
  node_timestepper["Time stepping<br/>[time_stepper.py]"]
  node_triggers["Simulation triggers<br/>[triggers.py]"]
end

node_user(("Simulation user"))

node_user -.->|"configures runs"| node_api
node_api -->|"creates simulations"| node_problem
node_api -->|"uses inputs"| node_inputs
node_problem -->|"parses cell"| node_cellparser
node_problem -->|"builds variables"| node_components
node_problem -->|"sets up state"| node_warehouse
node_problem -->|"builds mesh"| node_mesh
node_problem -->|"delegates models"| node_modelhandler
node_problem -->|"uses FEM"| node_fem
node_problem -->|"sets time scheme"| node_timescheme
node_problem -->|"solves equations"| node_solver
node_problem -->|"advances time"| node_timestepper
node_problem -->|"checks triggers"| node_triggers
node_cellparser -->|"parses parameters"| node_parameters
node_components -->|"uses parsed structure"| node_cellparser
node_components -->|"computes properties"| node_modelhandler
node_cellparser -->|"supports scaling"| node_dimensions
node_mesh -->|"adapts Gmsh mesh"| node_gmsh
node_modelhandler -->|"discovers models"| node_registry
node_modelhandler -.->|"runs model hierarchy"| node_pxd
node_pxd -.->|"extends with physics"| node_electrochem
node_pxd -.->|"adds heat balance"| node_thermal
node_pxd -.->|"adds degradation"| node_degradation
node_pxd -.->|"supports particle models"| node_particles
node_electrochem -.->|"forms FEM equations"| node_fem
node_thermal -->|"uses FEM equations"| node_fem
node_degradation -->|"preprocesses FEM fields"| node_fem
node_particles -->|"preprocesses FEM fields"| node_fem
node_problem -.->|"exposes plots"| node_plot

click node_api "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/simulation_interface/battery_system.py"
click node_inputs "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/simulation_interface/inputs.py"
click node_problem "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/main.py"
click node_cellparser "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/parser.py"
click node_components "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/components.py"
click node_parameters "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/parameters.py"
click node_dimensions "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/dimensional_analysis.py"
click node_warehouse "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/warehouse.py"
click node_mesh "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/mesh/base_mesher.py"
click node_gmsh "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/mesh/gmsh_generator.py"
click node_registry "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/__init__.py"
click node_modelhandler "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/model_handler.py"
click node_pxd "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/PXD/base_model.py"
click node_electrochem "https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/PXD/electrochemical"
click node_thermal "https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/PXD/thermal"
click node_degradation "https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/PXD/degradation"
click node_particles "https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/particle_models"
click node_fem "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/fem_handler.py"
click node_timescheme "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/time_scheme.py"
click node_solver "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/solver.py"
click node_timestepper "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/time_stepper.py"
click node_triggers "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/triggers.py"
click node_plot "https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/helpers/plotview.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_api,node_inputs,node_problem,node_plot,node_user toneBlue
class node_cellparser,node_components,node_parameters,node_dimensions,node_warehouse,node_mesh,node_gmsh toneAmber
class node_registry,node_modelhandler,node_pxd,node_electrochem,node_thermal,node_degradation,node_particles toneMint
class node_fem,node_timescheme,node_solver,node_timestepper,node_triggers toneRose
```

## Components

### Simulation interface

- [Battery system API](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/simulation_interface/battery_system.py): `src/cideMOD/simulation_interface/battery_system.py`
- [Run inputs](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/simulation_interface/inputs.py): `src/cideMOD/simulation_interface/inputs.py`
- [Problem runtime](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/main.py): `src/cideMOD/main.py`
- [Result plotting](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/helpers/plotview.py): `src/cideMOD/helpers/plotview.py`

### Cell and geometry

- [Cell parser](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/parser.py): `src/cideMOD/cell/parser.py`
- [Cell components](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/components.py): `src/cideMOD/cell/components.py`
- [Cell parameters](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/parameters.py): `src/cideMOD/cell/parameters.py`
- [Dimensional analysis](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/dimensional_analysis.py): `src/cideMOD/cell/dimensional_analysis.py`
- [State warehouse](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/cell/warehouse.py): `src/cideMOD/cell/warehouse.py`
- [Mesh construction](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/mesh/base_mesher.py): `src/cideMOD/mesh/base_mesher.py`
- [Gmsh generation](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/mesh/gmsh_generator.py): `src/cideMOD/mesh/gmsh_generator.py`

### Battery physics

- [Model registry](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/__init__.py): `src/cideMOD/models/__init__.py`
- [Model handler](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/model_handler.py): `src/cideMOD/models/model_handler.py`
- [PXD model base](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/models/PXD/base_model.py): `src/cideMOD/models/PXD/base_model.py`
- [Electrochemistry](https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/PXD/electrochemical): `src/cideMOD/models/PXD/electrochemical`
- [Thermal model](https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/PXD/thermal): `src/cideMOD/models/PXD/thermal`
- [Degradation models](https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/PXD/degradation): `src/cideMOD/models/PXD/degradation`
- [Particle models](https://github.com/cidetec-energy-storage/cidemod/tree/main/src/cideMOD/models/particle_models): `src/cideMOD/models/particle_models`

### Numerical runtime

- [FEM handler](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/fem_handler.py): `src/cideMOD/numerics/fem_handler.py`
- [Time schemes](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/time_scheme.py): `src/cideMOD/numerics/time_scheme.py`
- [Nonlinear solver](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/solver.py): `src/cideMOD/numerics/solver.py`
- [Time stepping](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/time_stepper.py): `src/cideMOD/numerics/time_stepper.py`
- [Simulation triggers](https://github.com/cidetec-energy-storage/cidemod/blob/main/src/cideMOD/numerics/triggers.py): `src/cideMOD/numerics/triggers.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → Battery system API: configures runs
- Battery system API → Problem runtime: creates simulations (evidence: `src/cideMOD/simulation_interface/battery_system.py`)
- Battery system API → Run inputs: uses inputs (evidence: `src/cideMOD/simulation_interface/battery_system.py`)
- Problem runtime → Cell parser: parses cell (evidence: `src/cideMOD/main.py`)
- Problem runtime → Cell components: builds variables (evidence: `src/cideMOD/main.py`)
- Problem runtime → State warehouse: sets up state (evidence: `src/cideMOD/main.py`)
- Problem runtime → Mesh construction: builds mesh (evidence: `src/cideMOD/main.py`)
- Problem runtime → Model handler: delegates models (evidence: `src/cideMOD/main.py`)
- Problem runtime → FEM handler: uses FEM (evidence: `src/cideMOD/main.py`)
- Problem runtime → Time schemes: sets time scheme (evidence: `src/cideMOD/main.py`)
- Problem runtime → Nonlinear solver: solves equations (evidence: `src/cideMOD/main.py`)
- Problem runtime → Time stepping: advances time (evidence: `src/cideMOD/main.py`)
- Problem runtime → Simulation triggers: checks triggers (evidence: `src/cideMOD/main.py`)
- Cell parser → Cell parameters: parses parameters (evidence: `src/cideMOD/cell/parser.py`)
- Cell components → Cell parser: uses parsed structure (evidence: `src/cideMOD/cell/components.py`)
- Cell components → Model handler: computes properties (evidence: `src/cideMOD/cell/components.py`)
- Cell parser → Dimensional analysis: supports scaling (evidence: `src/cideMOD/cell/dimensional_analysis.py`)
- Mesh construction → Gmsh generation: adapts Gmsh mesh (evidence: `src/cideMOD/mesh/gmsh_adapter.py`)
- Model handler → Model registry: discovers models (evidence: `src/cideMOD/models/model_handler.py`)
- Model handler → PXD model base: runs model hierarchy
- PXD model base → Electrochemistry: extends with physics (evidence: `src/cideMOD/models/PXD/electrochemical/preprocessing.py`)
- PXD model base → Thermal model: adds heat balance (evidence: `src/cideMOD/models/PXD/thermal/equations.py`)
- PXD model base → Degradation models: adds degradation (evidence: `src/cideMOD/models/PXD/degradation/SEI/base_SEI.py`)
- PXD model base → Particle models: supports particle models
- Electrochemistry → FEM handler: forms FEM equations (evidence: `src/cideMOD/models/PXD/electrochemical/preprocessing.py`)
- Thermal model → FEM handler: uses FEM equations (evidence: `src/cideMOD/models/PXD/thermal/equations.py`)
- Degradation models → FEM handler: preprocesses FEM fields (evidence: `src/cideMOD/models/PXD/degradation/SEI/electron_migration/preprocessing.py`)
- Particle models → FEM handler: preprocesses FEM fields (evidence: `src/cideMOD/models/particle_models/SGM_basic/preprocessing.py`)
- Problem runtime → Result plotting: exposes plots
