How cea-metrocarac/cdsaxs works
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.