How arkadysamsonenkowork/mars works
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: spectra_manager Spectra manager · population Population · spin_model.py Spin model · optimization Optimization
Components 21
Domain model
Physical entities, constants, and bundled nuclear data.
- Spin model · Defines spin-system objects and interactions used across the library.
mars/spin_model.py - Constants · Physical constants and shared numeric values.
mars/constants.py - Particles · Typed particle definitions and bundled nuclear-property data.
mars/particles - Utils · Common helper routines used by multiple subsystems.
mars/utils.py
Numerical engines
Mesh generation, spectra computation, and time evolution.
- Mesher · Powder, crystal, and general sampling meshes for averaging and quadrature.
mars/mesher - Spectra manager · Coordinates line solving, integration, and line combination for spectra generation.
mars/spectra_manager - Resonance solvers · Field, frequency, fixed-field, and secular-approximation solvers.
mars/spectra_manager/res_line_solvers - Integration · Integrates spectral contributions over sampled orientations and lines.
mars/spectra_manager/spectral_integration.py - Line combiner · Combines line contributions into final spectra.
mars/spectra_manager/spectral_line_combiner.py - Population · Population kinetics, relaxation, thermal corrections, and matrix utilities.
mars/population - Contexts · Defines working bases and relaxation-parameter contexts.
mars/population/contexts.py - Transforms · Transforms parameters and operators between bases.
mars/population/transform.py - Relaxation · Lindblad, Redfield, and coupling-channel models for evolution.
mars/population/relaxation_channels - Populators · Alternative population-evolution strategies including density and stationary paths.
mars/population/populators
Interfaces
Reading, preprocessing, optimization, and visualization around the core engines.
- Optimization · Objective functions and fitter interface for parameter search.
mars/optimization - Bruker reader · Reads experimental Bruker EPR files into analysis-ready data.
mars/reader/bruker_reader.py - Processing · Denoising and base processing for experimental spectra.
mars/spectra_processing - Visualization · Level, transition, analysis, and time-resolved visual outputs.
mars/visualization
Connections 23
- 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.