New Module

Adding a submodule within an existing top-level module

Three file patterns exist in the project — choose the simplest that fits:

Pattern A — Leaf file (single file, no subdirectory):

src/stats/my_estimator.rs

Use when the implementation is self-contained in one file. Most stats/ and distributions/ modules follow this.

Pattern B — Root file + directory (multiple subfiles):

src/quant/my_module.rs          ← module root: doc header, pub mod, re-exports, shared traits
src/quant/my_module/
  engine.rs
  types.rs

Use when the module has 2+ logical components. Most quant/ modules (pricing, calibration, calendar, fx, bonds, vol_surface) follow this.

Pattern C — Directory with mod.rs (when root defines shared types):

src/stochastic/mc/
  mod.rs                         ← defines McEstimate<T> + pub mod declarations
  lsm.rs
  mlmc.rs

Use when the module root itself defines shared types alongside submodule declarations. The mc/ module and noise/fgn/ follow this.

Module root must contain

1. //! doc comment with LaTeX formula summarising the core concept
2. pub mod declarations for all submodules
3. pub use re-exports of user-facing types
4. Shared traits or types that submodules need (define at root, not in a subfile)

Registration

• Submodule within existing top-level: add pub mod my_module; in the parent's .rs file (alphabetical order)
• New top-level module: add pub mod my_module; in src/lib.rs (requires approval per dev-rules)
• Feature-gated module: #[cfg(feature = "my_feature")] pub mod my_module;

2. Trait integration map

Before writing code, determine which existing traits the new types should implement.

stochastic/ modules

quant/ modules

copulas/ modules

Blanket-impl chains (do NOT duplicate by hand)

FourierModelExt  ──blanket──▸  ModelPricer  ──blanket──▸  ModelSurface

Implement the lowest-level trait; upstream is automatic.

3. Extensibility — require a trait, not a concrete type

When a new module accepts a pluggable component, define or reuse a trait.

Pattern (from BusinessDayConvention::adjust):

pub fn my_function(calendar: &(impl CalendarExt + ?Sized)) -> NaiveDate {
    // works with &Calendar AND &dyn CalendarExt (trait objects)
}

The + ?Sized bound is required to also accept &dyn Trait.

If the module creates a new extensibility point:

1. Define the trait in the module root (e.g., my_module.rs)
2. Implement it for the built-in concrete type
3. Re-export it
4. Accept &(impl MyTrait + ?Sized) in functions, not the concrete type

4. Type requirements

Every new pub struct and pub enum must have:

Do NOT add Serialize / Deserialize — serde is not a dependency.

5. Numeric conventions

6. Re-export conventions

In the module root, re-export user-facing types only:

pub use engine::MyEngine;
pub use types::{MyConfig, MyResult};

Keep internal helpers pub(crate) or private. Match the pattern of sibling modules in the same top-level module.

7. Integration with existing pipelines

Pricing pipeline (quant)

If the module produces a pricer, verify it works with:

• build_surface_from_model(&dyn ModelPricer, …) — vol-surface construction
• build_surface_from_calibration(&dyn ToModel, …) — calibration → vol-surface

Calendar pipeline (quant)

If the module uses dates, verify it works with:

• BusinessDayConvention::adjust(date, &calendar) — business day adjustment
• ScheduleBuilder::new(…).calendar(cal).build() — schedule generation
• TimeExt::tau_with_dcc(dcc) — year fraction from dates

Process pipeline (stochastic)

If the module defines a stochastic process, verify:

• sample() returns the correct Output type
• sample_par(m) works (all fields must be Send + Sync)
• Noise inputs follow the SeedExt pattern if seeded

Distribution pipeline (distributions)

If the module defines a distribution, verify:

• DistributionSampler<T> is implemented for bulk sampling
• fill_slice() uses SIMD where possible
• sample_matrix() works for multi-core benchmarks

8. Feature gating

If the module requires an optional external dependency:

1. Add dependency with optional = true in Cargo.toml
2. Add feature: my_feature = ["dep:my_crate"]
3. Gate module: #[cfg(feature = "my_feature")] pub mod my_module;
4. Gate imports in shared code: #[cfg(feature = "my_feature")]

Default features remain default = [].

9. Testing and benchmarks

Every new module must include:

1. Comparison test (tests/my_module_test.rs):

   • Validate output against reference (QuantLib, Python, R, MATLAB, or paper's tables/figures)
   • Test trait integrations (e.g., custom CalendarExt impl, sample_par correctness)
   • Test edge cases (zero maturity, degenerate parameters, boundary conditions)

2. Criterion benchmark (benches/my_module.rs):

   • Benchmark the hot path
   • Register in Cargo.toml: [[bench]] name = "my_module" harness = false

3. Integration test — verify end-to-end with existing pipelines where applicable

10. Documentation

Every new file must have:

• //! doc header citing the paper/reference (title, authors, DOI or arXiv ID)
• LaTeX formula in the doc header
• /// docs on all public items

Quick checklist

Before marking a new module as done:

• Placed in the correct top-level module (stochastic/, quant/, stats/, distributions/, copulas/)
• Module root has LaTeX doc header and re-exports
• Registered in the parent module's .rs file (alphabetical order)
• All numerical code generic over FloatExt, arrays use ndarray
• Correct domain traits implemented (see §2 trait integration map)
• Extensibility points use traits, not concrete types (see §3)
• Debug, Clone, Display, Default derives on public types
• Send + Sync verified (no Rc, Cell, or unshared interior mutability)
• No hardcoded /365.0, /360.0, or /252.0
• Comparison test against reference implementation
• Criterion benchmark registered in Cargo.toml
• Scientific reference cited in file header
• cargo clippy clean