Skip to content

Rust workspace overview

The spectrafit-core Rust workspace is organized into 11 composable crates with a strict downward dependency hierarchy. This page is the entry point to all of them: the table records what each crate is responsible for, the graph shows how they depend on each other, and the cards at the end open the generated rustdoc for each one.

Crate structure

Each crate has a single responsibility. The dependency chain runs strictly downward.

The workspace is 11 crates. Foundations (types, models) and the faer-native trust-region core sit at the bottom; the four solver-method crates build on the core; graph/solver/builder compose them; core is the PyO3 cdylib at the top.

Crate Path Purpose
spectrafit-types crates/spectrafit-types Serde intermediate-representation (IR) types mirroring the Python schemas; ModelTypeStr (canonical wire strings via as_str()); CoreError
spectrafit-models crates/spectrafit-models Model trait + the full 37-kernel catalog (Gaussian … power_law_offset, mgh09_rational — the authoritative list is model_manifest! in spectrafit-types) with analytical/FD Jacobians; model_from_str, all_model_types()
spectrafit-trust-region crates/spectrafit-trust-region faer-native trust-region core (Δ-radius framework) shared by the LM/TRF/dogleg/geodesic/Newton-CG solvers; per-iteration Report (cost/grad/θ history)
spectrafit-levenberg-marquardt crates/spectrafit-levenberg-marquardt Levenberg–Marquardt family (LM / TRF / geodesic) on the trust-region core
spectrafit-dogleg crates/spectrafit-dogleg Powell's dogleg trust-region method on the core
spectrafit-newton-cg crates/spectrafit-newton-cg Matrix-free Newton-CG (Steihaug–Toint truncated conjugate gradients) trust-region method on the core
spectrafit-varpro crates/spectrafit-varpro Variable-projection (VarPro) solver
spectrafit-graph crates/spectrafit-graph directed acyclic graph (DAG) compiler (topo sort, cycle detection, free_mask param binding, TiedPlan for expr_edges); evaluate, evaluate_components, jacobian
spectrafit-solver crates/spectrafit-solver Strategy dispatch — ten solvers (lm = faer default, lm-legacy, trf, geodesic, dogleg, newton-cg, irls, global/DE, varpro, auto); post-fit statistics (\(\chi^2\), AIC, BIC, covariance)
spectrafit-builder crates/spectrafit-builder Typed Rust domain-specific language (DSL) for building a FitGraphSpec without hand-writing JSON; a #[cfg(test)] exhaustiveness gate forces every new ModelTypeStr variant to be wired
spectrafit-core crates/spectrafit-core cdylib maturin target; pyo3 #[pyfunction] fit / fit_arrays / fit_arrays_numpy / evaluate / evaluate_components / model_type_wire_strings; #[pymodule] _core

Dependency graph

An arrow means depends on, so it points from a crate to what it uses. spectrafit-types is the foundation everything reaches, which is why it has no outgoing arrows.

flowchart TD
  core["spectrafit-core<br/><small>cdylib → _core.so</small>"]
  builder["spectrafit-builder"]
  solver["spectrafit-solver"]
  dag["spectrafit-graph"]
  varpro["spectrafit-varpro"]
  lm["spectrafit-levenberg-marquardt"]
  dogleg["spectrafit-dogleg"]
  ncg["spectrafit-newton-cg"]
  trust["spectrafit-trust-region"]
  models["spectrafit-models"]
  types["spectrafit-types"]

  core --> solver
  core --> dag
  core --> types
  builder --> models
  builder --> types
  solver --> lm
  solver --> dogleg
  solver --> ncg
  solver --> varpro
  solver --> dag
  solver --> types
  varpro --> dag
  varpro --> models
  varpro --> types
  dag --> models
  dag --> types
  lm --> trust
  lm --> types
  dogleg --> trust
  dogleg --> types
  ncg --> trust
  ncg --> types
  trust --> types
  models --> types

Generated API docs, per crate

Built by cargo doc --workspace --no-deps and published alongside this site. Cards are ordered by dependency depth — foundation first, the PyO3 binding last — the same order as the graph above.

The rustdoc root (/rust-api/) redirects straight to this section, so anyone arriving from a bare crate-docs link lands on the crate list rather than on the top of this page.

  • spectrafit-types

    Serde IR types, ModelTypeStr, CoreError. The foundation every other crate reaches.

  • spectrafit-models

    The Model trait and the full kernel catalog, with analytical Jacobians.

  • spectrafit-trust-region

    faer-native trust-region core (the Δ-radius framework) shared by four solver families.

  • spectrafit-levenberg-marquardt

    The Levenberg–Marquardt family — LM, TRF, geodesic — on the trust-region core.

  • spectrafit-dogleg

    Powell's dogleg trust-region method.

  • spectrafit-newton-cg

    Matrix-free Newton-CG (Steihaug–Toint truncated CG).

  • spectrafit-varpro

    Variable projection, for separable problems where some parameters enter linearly.

  • spectrafit-graph

    The DAG compiler: topological sort, cycle detection, parameter binding, expression edges.

  • spectrafit-solver

    Structure-routed dispatch across the solver families, plus post-fit statistics.

  • spectrafit-builder

    A typed Rust DSL for building a FitGraphSpec, and the compile-time exhaustiveness gate.

  • spectrafit-core

    The PyO3 cdylib — every #[pyfunction] that Python calls.

Build commands

# Check all crates
cargo check --workspace

# Run all Rust unit tests
PYO3_PYTHON="$(uv run python -c 'import sys; print(sys.executable)')" \
  cargo test --workspace --lib

# Build and install the Python extension
uv run maturin develop

# Full Python test suite
PYTHONPATH=python uv run pytest -q tests/

Next steps

  • Add a new solver family — Extending SpectraFit-Core lists the crate-DAG rules a new crate must respect, and every touchpoint from the Solver enum to the binding audit.
  • See how these crates fit into one request — Architecture traces a fit from the Python API call through the DAG compiler to these Rust kernels and back.