Crate optionstratlib_core

Expand description

§optionstratlib-core

The core domain model of OptionStratLib: the types every other OptionStratLib crate builds on. It holds no pricing model, market data, strategy, backtesting or presentation code, and depends on no other OptionStratLib crate.

model: model::Options, model::Position, model::leg::Leg and its spot, future and perpetual legs, model::Trade, payoff contracts at expiry and checked Decimal helpers.
error: the errors those types raise.
utils: time frames and date helpers, the deterministic RNG, numeric helpers and utils::Len.
constants: library-wide numeric constants, market conventions and time units.

Monetary values are rust_decimal::Decimal or positive::Positive, and arithmetic on them is checked.

§Foundational types

Four standalone crates define the newtypes and enums every OptionStratLib crate shares. Core depends on them and re-exports their types unchanged, never wrapping or copying one, so a value reached through any path below is the same type as the original and needs no conversion. Each crate resolves to a single version across the workspace (make check-graph).

Type	Defining crate	Re-exported at
`Positive`, `PositiveError`, `is_positive`	`positive`	`optionstratlib_core::model`, `optionstratlib::model`; `Positive` also in `optionstratlib::prelude`
`pos_or_panic!`, `spos!`, `assert_pos_relative_eq!`	`positive`	`optionstratlib_core`, `optionstratlib::prelude`
`ExpirationDate`, `ExpirationDateError`	`expiration_date`	`optionstratlib_core::model`, `optionstratlib::model`; `ExpirationDate` also at the `optionstratlib` root and in its prelude
`Side`, `OptionStyle`, `Action`, `UnderlyingAssetType`	`financial_types`	`optionstratlib_core::model::types`; `Side` and `OptionStyle` also in `optionstratlib_core::model` and at the `optionstratlib` root; `Side`, `OptionStyle` and `Action` in its prelude
`OptionType`, `OptionBasicType`, `AsianAveragingType`, `BarrierType`, `BinaryType`, `LookbackType`, `RainbowType`	`option_type`	`optionstratlib_core::model::types`; `OptionType` and `RainbowType` also in `optionstratlib_core::model` and at the `optionstratlib` root; `OptionType` in its prelude
`DAYS_IN_A_YEAR`	`positive`	`optionstratlib_core::constants`, `optionstratlib::constants`
`StrictlyPositive`, `PositiveResult`, the other `positive::constants`; `ParseEnumError`; the day-count conventions (`DayCount`, `Actual360`, `Actual365Fixed`, `Thirty360US`)	`positive`; `financial_types`; `expiration_date`	not re-exported: name them through the defining crate

The facade’s optionstratlib::model is optionstratlib_core::model, so every core path above is also reachable with the optionstratlib::model prefix. Enabling schema adds ToSchema impls to these types; it does not change which type a path names.

§Imports: no prelude

This crate has no prelude module, by decision (#518). The module roots already are the curated entry points: model re-exports the domain types and the foundational ones (Options, Position, Trade, TradeStatus, ExpirationDate, Side, OptionStyle, OptionType, Positive), model::leg the leg types, and utils TimeFrame and Len.

Measured when the crate was extracted, counting explicit optionstratlib::{model,utils,constants}::… imports: 168 of the 178 example files import through the facade’s prelude::*, and the examples name 8 distinct core items explicitly (in 25 files). Tests and benches (139 files) name 31 distinct core items in 40 files, 18 of them through deep paths such as model::decimal::DecimalStats or utils::time::…. Nothing outside the workspace imports optionstratlib_core directly. The use is spread thinly across many items, so no small glob would cover it, and the few types every consumer needs are already one path away at the module roots. A crate glob would only duplicate those roots and make every future addition a prelude commitment. The facade prelude is M7-03’s to redesign.

use optionstratlib_core::model::leg::{Leg, LegAble, SpotPosition};
use optionstratlib_core::model::{
    ExpirationDate, OptionStyle, OptionType, Options, Position, Positive, Side, Trade,
};
use optionstratlib_core::utils::{Len, TimeFrame};
use optionstratlib_core::pos_or_panic;

§Place in the workspace

Depends on no other OptionStratLib crate; the foundational positive, expiration_date, financial_types and option_type, which it re-exports.
Must not depend on every other OptionStratLib crate (it is the bottom layer); make check-graph enforces the layering (ADR-0001 D9).
In the facade: always present: optionstratlib::{model, utils, constants}, the core errors in optionstratlib::error, the root types Options, ExpirationDate, OptionStyle, OptionType, RainbowType, Side and the root macros. The facade paths are the same types as the paths here; the ownership map lists every one with its feature.

Moving from 0.21? The 0.22 architecture and adoption guide maps each redesign to its replacement workflow; 0.22 keeps no compatibility with 0.21.

§Minimal example

use optionstratlib_core::model::{ExpirationDate, OptionStyle, OptionType, Options, Positive, Side};
use optionstratlib_core::pos_or_panic;
use rust_decimal_macros::dec;

// A call struck at 100 with the underlying at 105; the payoff at
// expiry needs no pricing model.
let option = Options::new(
    OptionType::European,
    Side::Long,
    "XYZ".to_string(),
    pos_or_panic!(100.0),
    ExpirationDate::Days(pos_or_panic!(30.0)),
    pos_or_panic!(0.2),
    Positive::ONE,
    pos_or_panic!(105.0),
    dec!(0.05),
    OptionStyle::Call,
    Positive::ZERO,
    None,
);
assert_eq!(option.payoff()?, dec!(5));

§Runnable example

A runnable program that depends on this crate directly, with the smallest dependency set and no facade, is osl-example-direct-pricing; make tree-example-direct-pricing asserts its resolved graph. Core is in every example’s graph; this is the smallest program that uses it.

§Features

schema (off by default): derives utoipa::ToSchema on the core types and enables the same derive on positive, expiration_date, financial_types and option_type.

Modules§

constants: Library-wide numeric constants, market conventions and time units.
error: Errors raised by the core domain types. Errors owned by the core layer.
model: Domain types: options, positions, legs, trades, payoffs and checked Decimal helpers.
utils: Time frames, date helpers, the deterministic RNG and numeric helpers.

Macros§

assert_decimal_eq: Asserts that two Decimal values are approximately equal within a given epsilon
assert_pos_relative_eq: Asserts that two Positive values are relatively equal within a given epsilon.
d2f: Converts a Decimal value to f64 with error propagation.
d2fu: Converts a Decimal value to f64 without error checking.
f2d: Converts an f64 value to Decimal with error propagation.
f2du: Converts an f64 value to Decimal without error checking.
impl_json_debug: Implements Debug as compact JSON for one or more Serialize types.
impl_json_debug_pretty: Implements Debug as indented JSON for one or more Serialize types.
impl_json_display: Implements Display as compact JSON for one or more Serialize types.
nz: Builds a NonZeroUsize from a literal or constant expression.
pos_or_panic: Macro for creating a new Positive value that panics on invalid input.
spos: Macro for creating an optional Positive value from the given expression.

Constants§

VERSION: Version of the optionstratlib-core crate.