ospf-rust

🇺🇸 English | 🇨🇳 简体中文

Introduction

ospf-rust is the Rust implementation and migration workspace for OSPF. It provides base utilities, mathematical foundations, physical quantities, optimization core modeling, framework-level solver orchestration, and domain frameworks for BPP3D, CSP1D, and Gantt scheduling.

For the broader OSPF project and published documentation, see:

• ospf: https://github.com/fuookami/ospf
• documentation: https://fuookami.github.io/ospf/

Scope

This workspace owns reusable Rust crates and framework migrations. It keeps domain-independent infrastructure, optimization modeling primitives, and reusable domain frameworks in the repository.

Explicit non-goals:

1. Business-specific request protocols, tenant context, formula languages, and runtime deployment adapters.
2. External renderer implementations.
3. Solver installation and license management beyond feature-gated adapter documentation.

Module Structure

Rust crate	Kotlin boundary	Responsibility
ospf-rust-base	ospf-kotlin-utils foundation	Error handling, indexed types, collections, containers, iterators, and cloneable function helpers.
ospf-rust-multiarray	ospf-kotlin-multiarray	Generic multi-dimensional arrays, shapes, views, storage order, and block arrays.
ospf-rust-math	ospf-kotlin-math	Algebra, geometry, ordinary math, operators, chaotic systems, fractals, combinatorics, and symbolic computation.
ospf-rust-quantities	ospf-kotlin-quantities	Physical dimensions, units, compile-time/runtime quantities, and quantity-aware arithmetic.
ospf-rust-core	ospf-kotlin-core	Variables, tokens, symbols, MetaModel, flattening, solver traits, solver output, IIS, and backend adapters.
ospf-rust-framework	ospf-kotlin-framework	Pipeline modeling, shadow prices, column generation, Benders, combinatorial solvers, persistence contracts, remote solver client, and heartbeat utilities.
ospf-rust-framework-bpp3d	ospf-kotlin-framework-bpp3d	Reusable 3D bin-packing framework with BPP3D contexts, layer generation/assignment, packing, CSV fixtures, and renderer DTOs.
ospf-rust-framework-csp1d	ospf-kotlin-framework-csp1d	Reusable one-dimensional cutting-stock framework with material, generation, produce, yield, waste, length, and application flows.
ospf-rust-framework-gantt-scheduling	ospf-kotlin-framework-gantt-scheduling	Reusable Gantt scheduling framework with task, bunch, capacity, resource, produce, and branch-and-price flows.
ospf-rust-framework-network-scheduling	ospf-kotlin-framework-network-scheduling	Generic network flow, VRPTW, ESPPRC pricing, route compilation, and Branch-and-Price framework.
ospf-rust-example	ospf-kotlin-example	Runnable examples and migration compatibility demos.

Architecture Overview

The workspace follows a layered shape:

1. base, multiarray, math, and quantities provide reusable foundations.
2. core owns optimization modeling primitives and solver-facing model conversion.
3. framework adds solver orchestration, pipeline abstractions, shadow prices, persistence contracts, and remote solving.
4. domain framework crates assemble reusable business-domain modeling contexts around MetaModel.
5. example demonstrates current public flows and migration compatibility paths.

Framework domain crates should keep optimization semantics in context / aggregation / model component / pipeline layers. Application services coordinate solver selection, lifecycle, trace/KPI/render assembly, and recovery boundaries.

Constraint Programming Boundary

ospf-rust-core exposes an exact i64 constraint-programming model with immutable snapshots, stable IDs, source verification, and a unified SolveReport<i64>. The generic MIP lowerer uses checked i128 internally and only crosses the existing f64 solver boundary when every integer coefficient, bound, and generated Big-M is exactly representable; the current gate is 2^53.

The SCIP CP entry point is a feature-gated, strict finite MIP-backed facade. It is not a native SCIP/CIP CP backend. The declared CP capability scope is complete: generic MIP lowering returns verified ExactLowering for the supported finite subset and structured Unsupported for Cumulative, Circuit, Automaton, and Reservoir; raw cumulative FFI is a Conditional research probe, and true incremental CP sessions remain Unsupported. Snapshot-rebuild sessions are correct but must not be described as native incremental resume. The fake CP solver is for contract tests and small exhaustive oracles, not production search.

Documentation Templates

New or refreshed README files should follow:

• English template
• 中文模板

Crate-level README files use the full template. Internal src/domain, src/application, and src/infrastructure README files may use the shorter skeleton: responsibilities, file layout, public API, extension points, lifecycle/data flow, validation, and related modules.

Usage

Add workspace crates as path dependencies while developing inside this repository:

[dependencies]
ospf-rust-core = { path = "../ospf-rust-core" }
ospf-rust-framework = { path = "../ospf-rust-framework" }

Domain frameworks can be enabled directly:

[dependencies]
ospf-rust-framework-csp1d = { path = "../ospf-rust-framework-csp1d" }
ospf-rust-framework-gantt-scheduling = { path = "../ospf-rust-framework-gantt-scheduling" }
ospf-rust-framework-network-scheduling = { path = "../ospf-rust-framework-network-scheduling" }

Local Validation

cargo check --workspace
cargo test --workspace --no-run

For focused development, prefer package-level checks such as:

cargo check -p ospf-rust-core
cargo test -p ospf-rust-framework-csp1d

Solver-backed tests require the corresponding Cargo feature and local solver installation or bundled support. See the core solver notes for Gurobi and SCIP.

Feature gating and test coverage

Every crate declares default = [], and a large share of the suite sits behind non-default features:

• ospf-rust-math's scalar_parser and expression-parsing tests need parser; likewise serde.
• serde-dependent tests in ospf-rust-core need serde. The whole CP checkpoint module in ospf-rust-core (solver::constraint_programming::checkpoint) sits behind #[cfg(feature = "serde")], so a plain cargo test -p ospf-rust-core silently skips every one of its tests (including complete_hint_* and several cancellation-chain tests). Add --features serde when checking CP checkpoint coverage.
• ospf-rust-framework's remote module (including RemoteSolverFailureDetail) needs remote-solver; the checkpoint envelope wire-contract test tests/checkpoint_wire_contract.rs is also compiled and run only under --features remote-solver.

A plain cargo test --workspace therefore silently skips those tests. Enable them explicitly when measuring coverage:

# Workspace-wide, including remote, excluding async
cargo test --workspace --features "ospf-rust-math/parser ospf-rust-math/serde ospf-rust-core/serde ospf-rust-framework/remote-solver"

async switches the solver traits to a future-returning shape. remote-solver does not imply async, so remote tests can run alongside the whole workspace.

To enable async you must turn on each downstream crate's own async at the same time. Enabling it only on ospf-rust-framework leaves bpp3d and gantt — which still use the synchronous signature — failing to compile (a half-open state caused by feature unification):

cargo test --workspace --features "ospf-rust-framework/async ospf-rust-framework-bpp3d/async ospf-rust-framework-gantt-scheduling/async"

solver-backed tests additionally require the Gurobi/SCIP features plus local libraries and licenses.

Note: gurobi10, gurobi11, and gurobi12 are mutually exclusive — do not use --all-features; use the explicit feature list above.

Current Boundaries

This repository is actively migrating Kotlin framework capabilities into Rust. Some domain crates expose Kotlin-aligned public surfaces while still using Rust-side deterministic, fake, or feature-gated solver paths for parts of the lifecycle. Each domain crate README records its own current coverage and known gaps.

ospf-rust-framework-network-scheduling is wired into the workspace and its 99/99 migration is complete, with offline graph/flow, VRPTW, ESPPRC, route-compilation, and Branch-and-Price coverage. Its Gurobi/SCIP Demo5 validation remains feature-gated and depends on the local native solver environment; the crate README records the long-lived numeric, correctness, and E2E boundaries.

Related Modules

• OSPF Kotlin workspace
• OSPF Rust examples

License

This project is licensed under the MIT License. See LICENSE for details.