Struct Options 

pub struct Options {

    pub option_type: OptionType,
    pub side: Side,
    pub underlying_symbol: String,
    pub strike_price: Positive,
    pub expiration_date: ExpirationDate,
    pub implied_volatility: Positive,
    pub quantity: Positive,
    pub contract_size: Positive,
    pub underlying_price: Positive,
    pub risk_free_rate: Decimal,
    pub option_style: OptionStyle,
    pub dividend_yield: Positive,
    pub exotic_params: Option<ExoticParams>,
}

Represents a financial option contract with its essential parameters and characteristics.

This structure contains all the necessary information to define an options contract, including its type (call/put), market position (long/short), pricing parameters, and contract specifications. It serves as the core data model for option pricing, risk analysis, and strategy development.

The Options struct supports both standard option types and exotic options through the optional exotic_params field, making it versatile for various financial modeling scenarios.

Contract size

quantity counts contracts and contract_size is the multiplier: the units of the underlying one contract covers (100 for a standard US equity option, 1 by default). Their product, Options::position_size, is the position in units of the underlying, and it scales everything that is a money amount or an exposure of the whole position:

• the payoff and intrinsic value (payoff, payoff_at_price, intrinsic_value) and the P&L built on them;
• every Greek, which is reported per position, not per unit;
• the premium paid or received by a Position holding the option.

Prices from the pricing models stay per unit of the underlying, which is how a premium is quoted. Fees are charged per contract by Position and do not scale with the multiplier. With a contract size of 1 every figure is the per-unit figure times quantity, as before the field existed.

Fields

option_type: OptionType

Specifies whether this is a European or American option

side: Side

Indicates whether the position is Long (purchased) or Short (sold/written), which determines the profit/loss direction and risk profile.

underlying_symbol: String

The ticker symbol or identifier of the underlying asset (e.g., “AAPL” for Apple stock).

strike_price: Positive

The price at which the option holder can exercise their right to buy (for calls) or sell (for puts) the underlying asset.

expiration_date: ExpirationDate

When the option contract expires, either as days from now or as a specific date.

implied_volatility: Positive

The market’s expectation for future volatility of the underlying asset, a key parameter for option pricing models.

quantity: Positive

The number of contracts in this position.

contract_size: Positive

The contract multiplier: units of the underlying covered by one contract (100 for a standard US equity option, other sizes for futures options). Defaults to 1, so one contract covers one unit of the underlying, and payloads written before the field existed deserialize unchanged.

Payoff, intrinsic value, premium, P&L and Greeks of the position scale by quantity × contract_size (see Options::position_size). Prices returned by the pricing models stay per unit of the underlying, and crate::model::Position fees stay per contract.

underlying_price: Positive

The current market price of the underlying asset.

risk_free_rate: Decimal

The current risk-free interest rate used in option pricing models, typically based on treasury yields of similar duration. Annual, as a fraction; may be negative (#709).

option_style: OptionStyle

The option is a Call or Put option, determining the fundamental right option can be exercised.

dividend_yield: Positive

The annualized dividend yield of the underlying asset, affecting option pricing particularly for longer-dated contracts.

exotic_params: Option<ExoticParams>

Additional parameters required for exotic option types like Asian or Lookback options. This field is None for standard (vanilla) options.

Implementations

impl Options

pub fn new( option_type: OptionType, side: Side, underlying_symbol: String, strike_price: Positive, expiration_date: ExpirationDate, implied_volatility: Positive, quantity: Positive, underlying_price: Positive, risk_free_rate: Decimal, option_style: OptionStyle, dividend_yield: Positive, exotic_params: Option<ExoticParams>, ) -> Self

Creates a new options contract with the specified parameters.

This constructor creates an instance of Options with all the required parameters for defining and pricing an option contract. It supports both standard (vanilla) options and exotic options through the optional exotic_params parameter.

Parameters

• option_type - Specifies whether this is a Call or Put option, determining the fundamental right the option contract provides.
• side - Indicates whether the position is Long (purchased) or Short (sold/written), which determines the profit/loss direction.
• underlying_symbol - The ticker symbol or identifier of the underlying asset (e.g., “AAPL”).
• strike_price - The price at which the option can be exercised, represented as a Positive value.
• expiration_date - When the option contract expires, either as days from now or as a specific date.
• implied_volatility - The market’s expectation for future volatility of the underlying asset, a key parameter for option pricing.
• quantity - The number of contracts in this position, represented as a Positive value.
• underlying_price - The current market price of the underlying asset.
• risk_free_rate - The current risk-free interest rate used in option pricing models.
• option_style - The option exercise style (European or American), determining when the option can be exercised.
• dividend_yield - The annualized dividend yield of the underlying asset, affecting option pricing.
• exotic_params - Additional parameters required for exotic option types. Set to None for standard (vanilla) options.

Returns

A fully configured Options instance with all the specified parameters.

pub fn with_contract_size(self, contract_size: Positive) -> Self

Returns the option with its contract multiplier set to contract_size.

Options::new builds a contract that covers one unit of the underlying; chain this to size it in market contracts, for example .with_contract_size(Positive::HUNDRED) for a standard US equity option. A zero multiplier is accepted here and rejected by validation, as a zero quantity is.

pub fn position_size(&self) -> OptionsResult<Positive>

The size of the position in units of the underlying: quantity × contract_size.

This is the factor that scales payoff, intrinsic value, premium, P&L and Greeks from one unit of the underlying to the whole position. With the default contract_size of 1 it is exactly quantity.

Errors

Returns OptionsError::ValidationError when the product overflows the Positive range.

pub fn time_to_expiration(&self) -> OptionsResult<Positive>

Calculates the time to expiration of the option in years.

This function computes the time remaining until the option’s expiration date, expressed as a positive decimal value representing years. This is a key parameter used in option pricing models.

Returns

• OptionsResult<Positive> - A result containing the time to expiration in years as a Positive value, or an error if the calculation failed.

Errors

Propagates any expiration_date::error::ExpirationDateError returned by ExpirationDate::get_years (wrapped as OptionsError::ExpirationDate) when the stored expiration cannot be converted to a positive year fraction (e.g. past expiration or invalid date).

pub fn is_long(&self) -> bool

Determines if the option position is long (purchased).

A long position indicates that the option has been bought, meaning the holder has the right to exercise the option according to its terms.

Returns

• bool - Returns true if the option is held as a long position, false otherwise.

pub fn is_short(&self) -> bool

Determines if the option position is short (written/sold).

A short position indicates that the option has been sold or written, meaning the holder has the obligation to fulfill the contract terms if the option is exercised.

Returns

• bool - Returns true if the option is held as a short position, false otherwise.

pub fn payoff(&self) -> OptionsResult<Decimal>

Calculates the intrinsic value (payoff) of the option at the current underlying price.

The payoff represents what the option would be worth if exercised immediately, based on the current market conditions. For out-of-the-money options, the payoff will be zero.

Returns

• OptionsResult<Decimal> - A result containing the calculated payoff as a Decimal value, adjusted for the position size (quantity × contract_size), or an error if the calculation failed.

This method is useful for determining the exercise value of an option and for analyzing whether an option has intrinsic value.

Errors

Returns OptionsError::PayoffError when the size-scaled payoff is not representable as a Decimal (non-finite, or beyond the Decimal range). It previously returned Ok(Decimal::ZERO) for those inputs, which reported a deep in-the-money position as worthless.

Returns OptionsError::ValidationError when the position size quantity × contract_size overflows the Positive range.

Barrier options

No path is known here, only underlying_price, so the PayoffInfo carries no spot_min / spot_max and a barrier counts as hit only when underlying_price is at or beyond it (≥ for an up barrier, ≤ for a down one). An unhit knock-in pays its rebate and a hit knock-out pays its rebate, signed by the side. For a path-dependent payoff build a PayoffInfo with the observed extremes and call crate::model::payoff::Payoff::payoff on the option type.

Exotic options

The payoff is the contract’s terminal payoff, the value its pricing kernel returns at T = 0 (#844), signed by the side for every family. The option’s exotic_params reach the PayoffInfo, so a two-asset rainbow reads its second asset price and a cliquet its global cap and floor; observed Asian fixings and lookback extremes do not, so an Asian pays its intrinsic value on the spot and a floating-strike lookback pays 0, as a new contract does at expiry.

pub fn payoff_at_price(&self, price: &Positive) -> OptionsResult<Decimal>

Calculates the financial payoff value of the option at a specific underlying price.

This method determines the option’s payoff based on its type, strike price, style, and side (long/short) at the given underlying price. The result represents the total profit or loss for the option position at that price, adjusted by the position size (quantity × contract_size).

Parameters

• price - A Positive value representing the hypothetical price of the underlying asset.

Returns

• OptionsResult<Decimal> - The calculated payoff value as a Decimal, wrapped in a Result type. Returns an Err if the payoff calculation encounters an error.

Errors

Returns OptionsError::PayoffError when the size-scaled payoff at price is not representable as a Decimal (non-finite, or beyond the Decimal range). It previously returned Ok(Decimal::ZERO) for those inputs, which reported a deep in-the-money position as worthless.

Returns OptionsError::ValidationError when the position size quantity × contract_size overflows the Positive range.

pub fn intrinsic_value( &self, underlying_price: Positive, ) -> OptionsResult<Decimal>

Calculates the intrinsic value of the option.

The intrinsic value is the difference between the underlying asset’s price and the option’s strike price. For call options, the intrinsic value is the maximum of zero and the difference between the underlying price and the strike price. For put options, the intrinsic value is the maximum of zero and the difference between the strike price and the underlying price.

Arguments

• underlying_price - The current price of the underlying asset.

Returns

• OptionsResult<Decimal> - The intrinsic value of the option, or an error if the calculation fails.

Errors

Returns OptionsError::PayoffError when the size-scaled intrinsic value is not representable as a Decimal (non-finite, or beyond the Decimal range). It previously returned Ok(Decimal::ZERO) for those inputs, which reported a deep in-the-money position as worthless.

Returns OptionsError::ValidationError when the position size quantity × contract_size overflows the Positive range.

pub fn is_in_the_money(&self) -> bool

Determines whether an option is “in-the-money” based on its current price relative to strike price.

An option is considered in-the-money when:

• For Call options: the underlying asset price is greater than or equal to the strike price
• For Put options: the underlying asset price is less than or equal to the strike price

This status is important for evaluating the option’s current value and potential profitability.

Returns

true if the option is in-the-money, false otherwise

Trait Implementations

impl Clone for Options

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ComposeSchema for Options

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Debug for Options

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Options

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Options

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Options

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Options

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Options

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Options

impl ToSchema for Options

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.