# arkadysamsonenkowork/mars architecture

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

- Interactive diagram: https://gitdiagram.com/arkadysamsonenkowork/mars
- Repository: https://github.com/arkadysamsonenkowork/mars

## Overview

1. **Overall shape**
   MarS is a Python scientific-computing library centered on EPR simulation and fitting. The architecture is layered: low-level physics objects and constants, mid-level numerical kernels for spectra and population dynamics, and higher-level orchestration for optimization, reading experimental data, and visualization.

2. **Core domain model: spin systems**
   The `mars/spin_model.py`, `mars/constants.py`, `mars/utils.py`, and `mars/particles` packages define the physical entities used everywhere else: electrons, nuclei, interaction tensors, and spin-system configuration. The `particles/nuclei_db` files are a bundled data source for nuclear properties, which feeds model construction.

3. **Interaction and basis handling**
   The `mars/population/contexts.py`, `mars/population/transform.py`, `mars/population/matrix_generators.py`, and the docs under `contents/context` show a major architectural boundary around basis transformations. Relaxation and kinetic parameters can be expressed in multiple bases and transformed into the working basis before simulation. This is important because it separates user-facing physics specification from internal matrix computations.

4. **Spectra simulation pipeline**
   Continuous-wave and related spectra are produced by `mars/spectra_manager`. This subsystem is the main orchestration layer for spectral calculations: it combines the spin system, sample orientation/broadening, and resonance-line solvers under `res_line_solvers`, then applies spectral integration and line combination logic. The README’s CW EPR example maps directly to this layer.

5. **Orientation and sampling / meshing**
   `mars/mesher` provides the orientation and parameter-space sampling machinery used to average over powders, crystals, or other distributions. Files like `axial_mesh.py`, `delanay_mesh.py`, `general_mesh.py`, and `experimental.py` indicate that numerical quadrature / mesh generation is a distinct subsystem feeding spectra calculations rather than being embedded in them.

6. **Population dynamics and time-resolved EPR**
   `mars/population` is the time-resolved engine. It contains population kinetics, relaxation channels, parametric dependence profiles/rates, thermal corrections, and numerical integration utilities. The `populators` subpackage represents different solution strategies for time evolution of populations, while `relaxation_channels` encodes physical transition mechanisms such as Lindblad- and Redfield-style models.

7. **Density-matrix and superoperator path**
   The README describes both population kinetics and full density-matrix evolution. In the repository, this is reflected by the separation between population-focused modules and the “superoperator”/relaxation machinery in `population/relaxation_channels`, `population/tr_utils.py`, and the documentation on `superoperator_creation`. This is the main boundary between diagonal-state evolution and full Liouville-space evolution.

8. **Optimization and fitting**
   `mars/optimization` is the fitting layer. It wraps objectives, interaction parameter handling, and a fitter interface, and is designed to connect simulated spectra to external optimization libraries like Optuna and Nevergrad. Conceptually, this layer sits above spectra generation: it repeatedly calls the simulation stack while searching parameter space.

9. **Experimental data ingestion**
   `mars/reader/bruker_reader.py` is the main data-ingestion boundary. It reads Bruker EPR files and provides experimental datasets that can be processed, fit, or compared against simulations. This keeps raw instrument formats isolated from the simulation core.

10. **Signal processing and cleanup**
   `mars/spectra_processing` contains preprocessing utilities such as denoising and base processing abstractions. This layer sits between raw imported experimental data and fitting/analysis, enabling normalization or cleanup before spectra comparison.

11. **Visualization and analysis**
   `mars/visualization` provides plotting and diagnostic views for level structures, transitions, analysis summaries, and time-resolved results. It is a consumer of both simulated and experimental outputs, and is used for post-simulation interpretation rather than computation.

12. **Project infrastructure and validation**
   The repo is heavily documentation- and example-driven: `docs/` contains Sphinx docs and tutorial content, while `examples/` and `tests/` are mostly notebook-based scenario checks. The tests include quality comparisons against EasySpin outputs and timing benchmarks on CPU vs CUDA and different dtypes, which indicates performance portability is a first-class concern in the architecture.

13. **Execution model and numerical stack**
   The library is built around PyTorch tensors, with explicit support for CPU/CUDA and `float32`/`float64` precision. That choice shapes the architecture: most subsystems are written to pass tensor-valued physics objects through meshers, spectra calculators, population solvers, and fitting loops without leaving the PyTorch execution model.

14. **Key data flow**
   Typical flow is: construct spin system and sample → choose orientation mesh and broadening model → compute spectra or time evolution → optionally read experimental data and preprocess it → fit parameters via optimization → visualize and analyze results. The main architectural boundary is between physical model specification and the numerical engines that consume those models.

Main entry points: [`mars/spectra_manager`](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_manager) (Spectra manager), [`mars/population`](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population) (Population), [`mars/spin_model.py`](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spin_model.py) (Spin model), [`mars/optimization`](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/optimization) (Optimization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_domain["Domain model"]
  node_n_spin_model["Spin model<br/>physics core<br/>[spin_model.py]"]
  node_n_constants["Constants<br/>[constants.py]"]
  node_n_particles[("Particles<br/>particle db")]
  node_n_utils["Utils<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_grp_numerics["Numerical engines"]
  node_n_mesher["Mesher<br/>orientation sampling"]
  node_n_spectra_manager["Spectra manager<br/>cw spectra orchestration"]
  node_n_res_solvers["Resonance solvers<br/>line solvers"]
  node_n_spectral_integration["Integration"]
  node_n_line_combiner["Line combiner<br/>spectral combine"]
  node_n_population["Population<br/>time evolution"]
  node_n_contexts["Contexts<br/>basis context<br/>[contexts.py]"]
  node_n_transform["Transforms<br/>basis transform<br/>[transform.py]"]
  node_n_relaxation["Relaxation<br/>channels"]
  node_n_populators["Populators<br/>solver strategies"]
end

subgraph group_grp_interfaces["Interfaces"]
  node_n_optimization["Optimization<br/>fitting layer"]
  node_n_reader["Bruker reader<br/>data ingestion<br/>[bruker_reader.py]"]
  node_n_processing["Processing<br/>preprocess"]
  node_n_visualization["Visualization<br/>plots"]
end

subgraph group_grp_support["Support"]
  node_n_docs["Docs<br/>documentation"]
  node_n_examples["Examples<br/>usage demos"]
  node_n_tests["Tests<br/>validation"]
end

node_n_particles -->|"nuclear data"| node_n_spin_model
node_n_constants -->|"constants"| node_n_spin_model
node_n_utils -.->|"helpers"| node_n_spin_model
node_n_spin_model -->|"sampled by"| node_n_mesher
node_n_mesher -->|"averages"| node_n_spectra_manager
node_n_spin_model -->|"model input"| node_n_spectra_manager
node_n_spectra_manager -->|"solve lines"| node_n_res_solvers
node_n_spectra_manager -->|"integrate"| node_n_spectral_integration
node_n_spectra_manager -->|"combine"| node_n_line_combiner
node_n_contexts -->|"basis map"| node_n_transform
node_n_transform -->|"internal basis"| node_n_population
node_n_population -->|"channels"| node_n_relaxation
node_n_population -->|"strategies"| node_n_populators
node_n_population -.->|"time-resolved input"| node_n_spectra_manager
node_n_reader -->|"clean"| node_n_processing
node_n_processing -->|"prepared data"| node_n_optimization
node_n_spectra_manager -->|"simulate"| node_n_optimization
node_n_optimization -.->|"inspect"| node_n_visualization
node_n_spectra_manager -.->|"plot"| node_n_visualization
node_n_reader -.->|"compare"| node_n_visualization
node_n_docs -.->|"explains"| node_n_examples
node_n_tests -.->|"verifies"| node_n_spectra_manager
node_n_tests -.->|"verifies"| node_n_population

click node_n_spin_model "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spin_model.py"
click node_n_constants "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/constants.py"
click node_n_particles "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/particles"
click node_n_utils "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/utils.py"
click node_n_mesher "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/mesher"
click node_n_spectra_manager "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_manager"
click node_n_res_solvers "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_manager/res_line_solvers"
click node_n_spectral_integration "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spectra_manager/spectral_integration.py"
click node_n_line_combiner "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spectra_manager/spectral_line_combiner.py"
click node_n_population "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population"
click node_n_contexts "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/population/contexts.py"
click node_n_transform "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/population/transform.py"
click node_n_relaxation "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population/relaxation_channels"
click node_n_populators "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population/populators"
click node_n_optimization "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/optimization"
click node_n_reader "https://github.com/arkadysamsonenkowork/mars/blob/main/mars/reader/bruker_reader.py"
click node_n_processing "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_processing"
click node_n_visualization "https://github.com/arkadysamsonenkowork/mars/tree/main/mars/visualization"
click node_n_docs "https://github.com/arkadysamsonenkowork/mars/tree/main/docs/source"
click node_n_examples "https://github.com/arkadysamsonenkowork/mars/tree/main/examples"
click node_n_tests "https://github.com/arkadysamsonenkowork/mars/tree/main/tests"

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_n_spin_model,node_n_constants,node_n_particles,node_n_utils toneBlue
class node_n_mesher,node_n_spectra_manager,node_n_res_solvers,node_n_spectral_integration,node_n_line_combiner,node_n_population,node_n_contexts,node_n_transform,node_n_relaxation,node_n_populators toneAmber
class node_n_optimization,node_n_reader,node_n_processing,node_n_visualization toneMint
class node_n_docs,node_n_examples,node_n_tests toneRose
```

## Components

### Domain model

Physical entities, constants, and bundled nuclear data.

- [Spin model](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spin_model.py): physics core · Defines spin-system objects and interactions used across the library. · `mars/spin_model.py`
- [Constants](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/constants.py): physics constants · Physical constants and shared numeric values. · `mars/constants.py`
- [Particles](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/particles): particle db · Typed particle definitions and bundled nuclear-property data. · `mars/particles`
- [Utils](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/utils.py): shared helpers · Common helper routines used by multiple subsystems. · `mars/utils.py`

### Numerical engines

Mesh generation, spectra computation, and time evolution.

- [Mesher](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/mesher): orientation sampling · Powder, crystal, and general sampling meshes for averaging and quadrature. · `mars/mesher`
- [Spectra manager](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_manager): cw spectra orchestration · Coordinates line solving, integration, and line combination for spectra generation. · `mars/spectra_manager`
- [Resonance solvers](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_manager/res_line_solvers): line solvers · Field, frequency, fixed-field, and secular-approximation solvers. · `mars/spectra_manager/res_line_solvers`
- [Integration](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spectra_manager/spectral_integration.py): spectral integration · Integrates spectral contributions over sampled orientations and lines. · `mars/spectra_manager/spectral_integration.py`
- [Line combiner](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/spectra_manager/spectral_line_combiner.py): spectral combine · Combines line contributions into final spectra. · `mars/spectra_manager/spectral_line_combiner.py`
- [Population](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population): time evolution · Population kinetics, relaxation, thermal corrections, and matrix utilities. · `mars/population`
- [Contexts](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/population/contexts.py): basis context · Defines working bases and relaxation-parameter contexts. · `mars/population/contexts.py`
- [Transforms](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/population/transform.py): basis transform · Transforms parameters and operators between bases. · `mars/population/transform.py`
- [Relaxation](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population/relaxation_channels): channels · Lindblad, Redfield, and coupling-channel models for evolution. · `mars/population/relaxation_channels`
- [Populators](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/population/populators): solver strategies · Alternative population-evolution strategies including density and stationary paths. · `mars/population/populators`

### Interfaces

Reading, preprocessing, optimization, and visualization around the core engines.

- [Optimization](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/optimization): fitting layer · Objective functions and fitter interface for parameter search. · `mars/optimization`
- [Bruker reader](https://github.com/arkadysamsonenkowork/mars/blob/main/mars/reader/bruker_reader.py): data ingestion · Reads experimental Bruker EPR files into analysis-ready data. · `mars/reader/bruker_reader.py`
- [Processing](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/spectra_processing): preprocess · Denoising and base processing for experimental spectra. · `mars/spectra_processing`
- [Visualization](https://github.com/arkadysamsonenkowork/mars/tree/main/mars/visualization): plots · Level, transition, analysis, and time-resolved visual outputs. · `mars/visualization`

### Support

Documentation, examples, and validation assets.

- [Docs](https://github.com/arkadysamsonenkowork/mars/tree/main/docs/source): documentation · Sphinx docs, tutorials, and architectural explanations. · `docs/source`
- [Examples](https://github.com/arkadysamsonenkowork/mars/tree/main/examples): usage demos · Notebook-driven worked examples and article reproductions. · `examples`
- [Tests](https://github.com/arkadysamsonenkowork/mars/tree/main/tests): validation · Quality, timing, and architecture-check notebooks and benchmark assets. · `tests`

## Connections

- Particles → Spin model: nuclear data · Bundled particle data feeds spin-system construction.
- Constants → Spin model: constants · Shared physical constants support model definitions.
- Utils → Spin model: helpers · Utility routines are reused in core model code.
- Spin model → Mesher: sampled by · Spin systems are evaluated over orientation and parameter meshes.
- Mesher → Spectra manager: averages · Meshes provide quadrature/sampling for spectra calculations.
- Spin model → Spectra manager: model input · Spectra orchestration consumes spin-system definitions.
- Spectra manager → Resonance solvers: solve lines · Orchestrator delegates resonance-line calculations.
- Spectra manager → Integration: integrate · Spectral contributions are integrated into final signals.
- Spectra manager → Line combiner: combine · Line contributions are merged into spectra.
- Contexts → Transforms: basis map · Contexts define how quantities are interpreted and transformed.
- Transforms → Population: internal basis · Population solvers operate in the working basis.
- Population → Relaxation: channels · Relaxation channels drive population or Liouville-space evolution.
- Population → Populators: strategies · Different solver strategies produce stationary or dynamic solutions.
- Population → Spectra manager: time-resolved input · Population results can feed spectral creation workflows.
- Bruker reader → Processing: clean · Imported experimental data is preprocessed before comparison.
- Processing → Optimization: prepared data · Processed experiments become fitting objectives.
- Spectra manager → Optimization: simulate · Optimization repeatedly calls the simulation stack.
- Optimization → Visualization: inspect · Fits and parameter searches are visualized for analysis.
- Spectra manager → Visualization: plot · Simulated spectra and diagnostics are rendered for interpretation.
- Bruker reader → Visualization: compare · Experimental data can be plotted alongside simulations.
- Docs → Examples: explains · Documentation and examples reinforce each other.
- Tests → Spectra manager: verifies · Benchmarks and quality checks exercise core simulation paths.
- Tests → Population: verifies · Transformation and time-evolution notebooks validate population logic.
