Skip to content

API Reference

Complete API documentation for Diffid's Python and Rust interfaces.

Python API

Diffid provides a comprehensive Python API with full type hints and automatic documentation.

  • Builders

    Problem builders for different use cases: scalar functions, ODE fitting, and custom solvers.

    Builders

  • Optimisers

    Gradient-free (Nelder-Mead, CMA-ES) and gradient-based (Adam) optimisation algorithms.

    Optimisers

  • Samplers

    MCMC and nested sampling for posterior exploration and model comparison.

    Samplers

  • Cost Metrics

    Metrics for comparing model predictions to observations (SSE, RMSE, GaussianNLL).

    Cost Metrics

  • Results

    Result objects returned by optimisers and samplers with diagnostics.

    Results

Rust API

The Rust core provides high-performance implementations of all algorithms.

Rust Documentation on docs.rs

Module Structure

diffid/
├── ScalarBuilder        # Direct function optimisation
├── DiffsolBuilder       # ODE fitting with DiffSL/Diffsol
├── VectorBuilder        # Custom solver integration
├── Problem              # Built problem instance
├── Optimisers
│   ├── NelderMead       # Simplex gradient-free optimiser
│   ├── CMAES            # Covariance matrix adaptation
│   └── Adam             # Adaptive moment estimation
├── Samplers
│   ├── MetropolisHastings  # MCMC sampling
│   └── DynamicNestedSampling  # Evidence calculation
├── CostMetric           # Cost/likelihood metrics
└── OptimisationResults  # Result container

Type Hints

All Python functions include comprehensive type hints:

from diffid import ScalarBuilder, CMAES, OptimisationResults
import numpy.typing as npt

def optimize_function(
    func: Callable[[npt.NDArray[np.float64]], npt.NDArray[np.float64]],
    initial_params: dict[str, float]
) -> OptimisationResults:
    builder = ScalarBuilder().with_objective(func)
    for name, value in initial_params.items():
        builder = builder.with_parameter(name, value)

    problem = builder.build()
    optimiser = CMAES().with_max_iter(1000)
    return optimiser.run(problem, list(initial_params.values()))

Type stubs are automatically generated from the Rust implementation and are available in IDE completions.

Conventions

Parameter Order

All builders maintain parameter order based on the sequence of .with_parameter() calls:

builder = (
    diffid.ScalarBuilder()
    .with_parameter("x", 1.0)  # Index 0
    .with_parameter("y", 2.0)  # Index 1
)

result = problem.optimise()
print(result.x)  # [optimal_x, optimal_y]

Return Types

  • Optimisers return OptimisationResults with .x, .value, .success, etc.
  • Samplers return sampling-specific results with .samples, .log_likelihood, etc.
  • All results include diagnostic information

Array Conventions

  • Input: Python callables accept NumPy arrays
  • Output: Python callables must return NumPy arrays
  • Data: Data arrays are (n_timepoints, n_variables + 1) with time in first column

Next Steps