# cea-metrocarac/cdsaxs architecture

> Architecture diagram of the GitHub repository cea-metrocarac/cdsaxs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cea-metrocarac/cdsaxs
- Repository: https://github.com/cea-metrocarac/cdsaxs

## Overview

##### Main components
- Simulation Models – These reside primarily in the src/cdsaxs/simulations directory. They include the implementation of the Stacked Trapezoid and Strong Castle models. These models calculate the Fourier transforms that represent the scattering intensity, using the provided analytical equations.
- Fitting and Residual Calculation – Located in src/cdsaxs (files like fitter.py and residual.py), this component takes the simulated intensity profiles, compares them against experimental data (obtained from CD-SAXS measurements), and computes the “goodness of fit.”
- Optimization Algorithms – While not immediately visible as separate modules in the file tree, the README explains that the package uses the Covariance Matrix Adaptation Evolution Strategy (CMAES) and Monte Carlo Markov Chain (MCMC) methods (using the deap and emcee libraries respectively) to optimize simulation parameters and explore parameter uncertainty.
- Testing and Documentation – The tests folder contains unit tests supporting each component’s functionality. The docs and Tutorials folders (including Jupyter notebooks) serve as the user and developer documentation and learning resources.
- CI/CD Integration – Indicate the GitHub workflows (in .github/workflows) that automate tests and build documentation on every commit.

##### Relationships and interactions
- Data Flow: Start with experimental data (from synchrotron experiments) that are used as input. The simulation component (with its distinct model types) generates theoretical intensity profiles via Fourier transforms.
- The Fitting Engine takes these simulated outputs and—in conjunction with error functions (calculation of mean-absolute error between simulation and experiment)—feeds the results into the optimization module.
- The Optimization Module (using CMAES and MCMC) iteratively adjusts simulation parameters, continually looping with the simulation and fitting components until convergence is reached.
- Optionally, if GPU capability is available (via Cupy), parts of the simulation or optimization process are offloaded to accelerate computation.
- Testing and Documentation are on the “periphery” to ensure quality and ease of use; contributions and reproducibility (via examples and tutorials) are a prominent aspect.

##### Architectural patterns and design principles
- Modularity: The package is organized by separating simulation logic, fitting routines, and optimization strategies. Each module clearly handles a different concern.
- Separation of Concerns: The distinction between simulation (physical model computations) and data fitting (comparing simulation to experiment) is critical. Likewise, the optimization strategies are abstracted away from the simulation code.
- Extensibility: New simulation models or optimization methods could be added following the same pattern (as evidenced by separate simulation modules and test files).
- Testability and Documentation: There are dedicated directories for tests and extensive documentation (both narratively in the README and in standalone tutorials).

##### Relevant technologies, frameworks, and libraries
- Python – The core language with package/module management in src/.
- GPU Acceleration – Implemented via Cupy (if installed as cdsaxs[gpu]).
- Optimization Libraries – deap (for CMAES) and emcee (for MCMC).
- Documentation – Sphinx is indicated by the docs/source/conf.py and related files.
- CI/CD – GitHub Actions workflows (.github/workflows/ci.yml) automate testing and builds.

- Clear labels for each component (e.g., “Simulation Models (Stacked Trapezoid and Strong Castle)”, “Fitting Module”, “CMAES Optimizer”, “MCMC Uncertainty Explorer”, “GPU Support (Cupy)”, “Unit Tests”, “Documentation & Tutorials”, and “CI/CD Pipeline”).
- Optionally, annotate with notes on key algorithms (the Fourier transformation formulas, goodness-of-fit computation, etc.) or critical dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Input
    ED("Experimental Data"):::input

    %% Simulation Models Subgraph
    subgraph "Simulation Models"
        ST("Stacked Trapezoid Model"):::simulation
        SC("Strong Castle Model"):::simulation
        GPU("GPU Acceleration (Cupy)"):::gpu
    end

    %% Fitting Components Subgraph
    subgraph "Fitting & Residual Calculation"
        FIT("Fitter"):::fitting
        RES("Residual Calculation"):::fitting
    end

    %% Optimization Module Subgraph
    subgraph "Optimization Module"
        CMA("CMAES Optimizer"):::optimization
        MCMC("MCMC Uncertainty Explorer"):::optimization
    end

    %% Peripheral Components
    TEST("Unit Tests"):::testing
    DOC("Documentation"):::documentation
    TUT("Tutorials"):::documentation
    CI("CI/CD Pipeline"):::ci

    %% Data Flow Connections
    ED -->|"input"| ST
    ED -->|"input"| SC

    ST -->|"simulate->output"| FIT
    SC -->|"simulate->output"| RES

    FIT -->|"simulate vs experiment"| CMA
    RES -->|"error computation"| MCMC

    %% Feedback loop: Optimization feeds parameter updates to Simulation
    CMA -->|"update parameters"| ST
    MCMC -->|"update parameters"| SC

    %% GPU support connection (used by both Simulation and Optimization)
    GPU --- ST
    GPU --- SC
    GPU --- CMA
    GPU --- MCMC

    %% Peripheral Connections (not in main data loop)
    FIT --- TEST
    RES --- TEST
    DOC --- TUT
    DOC --- CI

    %% Click Events for Simulation Models
    click ST "https://github.com/cea-metrocarac/cdsaxs/blob/main/src/cdsaxs/simulations/stacked_trapezoid.py"
    click SC "https://github.com/cea-metrocarac/cdsaxs/blob/main/src/cdsaxs/simulations/strong_castle.py"

    %% Click Events for Fitting Components
    click FIT "https://github.com/cea-metrocarac/cdsaxs/blob/main/src/cdsaxs/fitter.py"
    click RES "https://github.com/cea-metrocarac/cdsaxs/blob/main/src/cdsaxs/residual.py"

    %% Click Event for Testing Infrastructure
    click TEST "https://github.com/cea-metrocarac/cdsaxs/tree/main/tests/"

    %% Click Events for Documentation & Tutorials
    click DOC "https://github.com/cea-metrocarac/cdsaxs/tree/main/docs/"
    click TUT "https://github.com/cea-metrocarac/cdsaxs/blob/main/Tutorials/stacked_trapezoid_simulation_and_fitting.ipynb"
    click TUT "https://github.com/cea-metrocarac/cdsaxs/blob/main/Tutorials/strong_castle_simulation.ipynb"

    %% Click Event for CI/CD Pipeline
    click CI "https://github.com/cea-metrocarac/cdsaxs/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef input fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef simulation fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef fitting fill:#cff4fc,stroke:#055160,stroke-width:2px;
    classDef optimization fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef gpu fill:#f8d7da,stroke:#842029,stroke-width:2px;
    classDef testing fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef documentation fill:#e2eafc,stroke:#27408b,stroke-width:2px;
    classDef ci fill:#fefefe,stroke:#6c757d,stroke-width:2px;
```
