Struct Position 

#[non_exhaustive]
pub struct Position {

    pub side: PositionSide,
    pub entry_timestamp: i64,
    pub entry_price: f64,
    pub quantity: f64,
    pub entry_quantity: f64,
    pub entry_commission: f64,
    pub entry_transaction_tax: f64,
    pub entry_signal: Signal,
    pub dividend_income: f64,
    pub unreinvested_dividends: f64,
    pub scale_in_count: usize,
    pub partial_close_count: usize,
    pub bracket_stop_loss_pct: Option<f64>,
    pub bracket_take_profit_pct: Option<f64>,
    pub bracket_trailing_stop_pct: Option<f64>,
}

An open position

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

side: PositionSide

Position direction

entry_timestamp: i64

Entry timestamp

entry_price: f64

Entry price (after slippage)

quantity: f64

Number of shares/units

entry_quantity: f64

Number of shares/units at entry (before any dividend reinvestment).

entry_commission: f64

Entry commission paid

entry_transaction_tax: f64

Transaction tax paid on entry (long entries and short covers only).

entry_signal: Signal

Signal that triggered entry

dividend_income: f64

Accumulated dividend income received while this position was open.

Added to trade P&L on close. Zero when dividends are not supplied to the engine or when the position receives no dividends.

unreinvested_dividends: f64

Dividend income that was NOT reinvested (i.e. remains as cash). Used internally for correct cash-accounting.

scale_in_count: usize

Number of times this position has been scaled into (pyramid adds).

Starts at 0 (initial entry). Incremented by Position::scale_in on each successful add.

partial_close_count: usize

Number of partial closes executed so far.

Used to assign a monotonically increasing Trade::scale_sequence to each Trade returned by Position::partial_close.

bracket_stop_loss_pct: Option<f64>

Per-trade stop-loss percentage override.

Populated from Signal::bracket_stop_loss_pct when the position is opened. Takes precedence over BacktestConfig::stop_loss_pct when Some. None means fall back to the config-level default.

bracket_take_profit_pct: Option<f64>

Per-trade take-profit percentage override.

Populated from Signal::bracket_take_profit_pct when the position is opened. Takes precedence over BacktestConfig::take_profit_pct when Some.

bracket_trailing_stop_pct: Option<f64>

Per-trade trailing stop percentage override.

Populated from Signal::bracket_trailing_stop_pct when the position is opened. Takes precedence over BacktestConfig::trailing_stop_pct when Some.

Implementations

impl Position

pub fn new( side: PositionSide, entry_timestamp: i64, entry_price: f64, quantity: f64, entry_commission: f64, entry_signal: Signal, ) -> Self

Create a new position.

pub fn current_value(&self, current_price: f64) -> f64

Net contribution of this position to portfolio equity at current_price.

Sign convention (important): returns a positive value for long positions and a negative value for short positions. The negative short value is deliberate: when the engine opens a short it credits cash with the sale proceeds (cash += entry_price × quantity), so the correct running equity is cash + current_value(price). As the price falls the negative value grows less negative, and the net equity rises — exactly the expected profit behaviour for a short.

If you need the raw notional exposure (always positive), use self.quantity * current_price directly.

pub fn unrealized_pnl(&self, current_price: f64) -> f64

Calculate unrealized P&L at given price (before exit commission)

pub fn unrealized_return_pct(&self, current_price: f64) -> f64

Calculate unrealized return percentage

pub fn is_profitable(&self, current_price: f64) -> bool

Check if position is profitable at given price

pub fn is_long(&self) -> bool

Check if this is a long position

pub fn is_short(&self) -> bool

Check if this is a short position

pub fn credit_dividend(&mut self, income: f64, close_price: f64, reinvest: bool)

Credit dividend cashflow to this position.

income must be pre-signed by the caller:

• Long positions receive dividends → pass +per_share × quantity
• Short positions owe dividends to the stock lender → pass -(per_share × quantity)

The engine’s credit_dividends helper handles this negation automatically. Passing an unsigned (always-positive) value to a short position would incorrectly record dividend income instead of a liability.

When reinvest is true, only positive income is reinvested into additional units (long-side reinvestment only).

pub fn scale_in( &mut self, fill_price: f64, additional_qty: f64, commission: f64, entry_tax: f64, )

Add shares to this position (pyramid / scale-in).

Updates the weighted-average entry_price and entry_quantity to reflect the blended cost basis and increments scale_in_count. The caller is responsible for debiting the entry cost from available cash and for applying slippage/spread to fill_price before calling this method.

Arguments

• fill_price – Adjusted entry price for the new shares.
• additional_qty – Number of shares to add. No-op if <= 0.0.
• commission – Commission paid for this add (already applied to cash).
• entry_tax – Transaction tax for this add (already applied to cash).

pub fn partial_close( &mut self, fraction: f64, exit_ts: i64, exit_price: f64, commission: f64, exit_tax: f64, signal: Signal, ) -> Trade

Partially close this position and return a completed Trade.

Closes fraction of the current position quantity, allocating a proportional share of accumulated entry costs and dividend income to the trade P&L. The remaining position stays open with reduced quantity, dividend balances, and entry cost bases.

Trade::is_partial is true for all trades returned by this method. For a full close prefer Position::close_with_tax, which sets is_partial = false. The engine’s scale_out_position delegates fraction >= 1.0 to close_position for exactly this reason.

The caller is responsible for updating cash from the returned trade’s exit proceeds.

Arguments

• fraction – Portion of current quantity to close (0.0..=1.0).
• exit_ts – Timestamp of the fill.
• exit_price – Adjusted exit price (after slippage/spread).
• commission – Exit-side commission for this close.
• exit_tax – Exit-side transaction tax for this close.
• signal – Signal that triggered the partial exit.

pub fn close( self, exit_timestamp: i64, exit_price: f64, exit_commission: f64, exit_signal: Signal, ) -> Trade

Close this position and create a Trade.

dividend_income accumulated during the hold is added to P&L and preserved on the returned Trade for reporting purposes.

Trait Implementations

impl Clone for Position

fn clone(&self) -> Position

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Position

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Position

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Position

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

where __S: Serializer,

Serialize this value into the given Serde serializer.