Skip to content

Architecture

Jump to bottom
@biface edited this page Apr 11, 2026 · 4 revisions

🇬🇧 English | 🇫🇷 Français

WHAT / HOW separation

oxiflow enforces a strict three-pole separation:

graph TD
    PM["PhysicalModel\n(declares)"]
    CC["ContextCalculator\n(computes)"]
    SV["Solver\n(orchestrates)"]
    SC["Scenario\n— WHAT pole —"]
    CF["SolverConfiguration\n— HOW pole —"]
    SR["SimulationResult"]
 
    PM -->|contains| SC
    CC -->|contains| CF
    SV -->|receives| SC
    SV -->|receives| CF
    SV -->|produces| SR
Loading
Pole Type Responsibility
WHAT Scenario Problem declaration: model, mesh, BCs, domains
HOW SolverConfiguration Solving parameters: integrator, step control, calculators
Execution Solver Orchestrates the time integration loop

Contractual execution order

Each time step must follow this order. Deviating produces silently incorrect results.

sequenceDiagram
    participant S as Solver
    participant CH as chain.rs
    participant CTX as ComputeContext
    participant BC as BoundaryConditions (J2)
    participant M as PhysicalModel
    participant I as Integrator
 
    S->>CH: build_calculator_chain()
    CH-->>S: ordered chain ✓ or MissingCalculator ✗
 
    loop each time step dt
        S->>CTX: calculators → topological order
        S->>BC: apply(u, ctx)
        S->>M: compute_physics(u, ctx) → du/dt
        S->>I: integrate(du/dt, dt) → u_next
    end
    S-->>S: SimulationResult
Loading

Mesh — INV-1 and module hierarchy

src/mesh/
├── mod.rs              ← Mesh trait + public re-exports
├── structured/
│   └── mod.rs          ← UniformGrid1D (J1)
└── unstructured/       ← RESERVED J7 (FEM)

No public API exposes dx, nx, or raw node indices. All spatial access goes through the Mesh trait (DD-007, DD-019).

ContextValue — two orthogonal axes

Axis Variant Active
Pointwise rank 0 Scalar(f64) J1
Logical flag Boolean(bool) J1
Pointwise rank 1 Vector(DVector) J1
Pointwise rank 2 Matrix(DMatrix) J1
Nodal scalar field ScalarField(DVector) J1
Nodal vector field VectorField(DMatrix) J1
Rank-4 tensor Tensor4 Reserved J7
Rank-2 tensor field TensorField Reserved J7

Tensors of rank > 4 are out of scope. Extension for third-party frameworks via INV-4.

FEM invariants

graph LR
    J1["v0.1.0\nINV-1\nAbstract Mesh"]
    J3["v0.3.0\nINV-3\nCouplingOperator"]
    J4["v0.5.0\nINV-2\nDiscreteOperator"]
    J7["v2.0.0\nINV-4\nPlugin-safe API"]
    J1 --> J3 --> J4 --> J7
Loading
INV Guarantee Active
INV-1 No dx/nx in public API v0.1.0
INV-2 Integrators decoupled from spatial scheme v0.5.0
INV-3 Inter-domain coupling only via CouplingOperator v0.3.0
INV-4 All public traits object-safe v2.0.0

Design decision index

See GitHub issues — type: decision

Clone this wiki locally