Margin Calculations¶

qlcore provides margin calculations for leveraged trading, including initial margin, maintenance margin, and margin utilization.

Initial Margin¶

The collateral required to open a position:

import qlcore as qc
from decimal import Decimal

# Basic calculation
initial = qc.calculate_initial_margin(
    notional="45000",    # Position notional value
    leverage=10,         # Desired leverage
)
print(f"Initial Margin: ${initial}")  # $4500

With Custom Rate¶

initial = qc.calculate_initial_margin(
    notional="45000",
    rate=Decimal("0.1"),  # 10% margin rate (same as 10x leverage)
)

Maintenance Margin¶

The minimum margin required to keep a position open:

maintenance = qc.calculate_maintenance_margin(
    notional="45000",
    rate=Decimal("0.005"),  # 0.5% maintenance rate
)
print(f"Maintenance Margin: ${maintenance}")  # $225

Margin Schedule¶

For tiered margin rates based on position size:

schedule = qc.MarginSchedule(
    tiers=[
        (Decimal("100000"), Decimal("0.01")),   # 1% for first $100k
        (Decimal("500000"), Decimal("0.02")),   # 2% for $100k-$500k
        (Decimal("1000000"), Decimal("0.05")),  # 5% for $500k-$1M
        (None, Decimal("0.10")),                # 10% above $1M
    ]
)

margin = schedule.calculate_margin(notional=Decimal("750000"))

Margin Levels¶

Track margin status:

level = qc.MarginLevel(
    equity=Decimal("5000"),
    initial_margin=Decimal("4500"),
    maintenance_margin=Decimal("225"),
)

print(f"Margin Ratio: {level.margin_ratio:.2%}")
print(f"Is Safe: {level.is_safe}")
print(f"Is Warning: {level.is_warning}")
print(f"Is Liquidatable: {level.is_liquidatable}")

Free Margin¶

Available margin for new positions:

free = qc.free_margin(
    equity=Decimal("10000"),
    used_margin=Decimal("4500"),
)
print(f"Free Margin: ${free}")  # $5500

Margin Utilization¶

Percentage of available margin in use:

utilization = qc.margin_utilization(
    used_margin=Decimal("4500"),
    total_margin=Decimal("10000"),
)
print(f"Utilization: {utilization:.1%}")  # 45%

Isolated Margin¶

Track margin for individual positions:

isolated = qc.IsolatedMargin(
    initial_margin=Decimal("4500"),
    maintenance_margin=Decimal("225"),
    margin_balance=Decimal("5000"),
)

print(f"Initial: ${isolated.initial_margin}")
print(f"Maintenance: ${isolated.maintenance_margin}")
print(f"Balance: ${isolated.margin_balance}")

Margin Requirements¶

Complete margin calculation result:

requirements = qc.MarginRequirements(
    initial=Decimal("4500"),
    maintenance=Decimal("225"),
    max_leverage=Decimal("20"),
)

Complete Example¶

import qlcore as qc
from decimal import Decimal

# Position parameters
notional = Decimal("45000")
leverage = 10
mm_rate = Decimal("0.005")

# Calculate margins
initial = qc.calculate_initial_margin(notional, leverage)
maintenance = qc.calculate_maintenance_margin(notional, mm_rate)

# Check margin status
equity = Decimal("5000")
used = initial

free = qc.free_margin(equity, used)
utilization = qc.margin_utilization(used, equity)

print("Margin Summary")
print("-" * 30)
print(f"Notional:     ${notional:>10}")
print(f"Leverage:     {leverage:>10}x")
print(f"Initial:      ${initial:>10}")
print(f"Maintenance:  ${maintenance:>10}")
print(f"Equity:       ${equity:>10}")
print(f"Free Margin:  ${free:>10}")
print(f"Utilization:  {utilization:>10.1%}")

Using Namespace¶

import qlcore as qc

qc.margin.calculate_initial_margin("45000", leverage=10)
qc.margin.calculate_maintenance_margin("45000", rate="0.005")
qc.margin.free_margin(equity, used)
qc.margin.margin_utilization(used, total)
qc.margin.MarginRequirements(...)
qc.margin.MarginLevel(...)
qc.margin.MarginSchedule(...)
qc.margin.IsolatedMargin(...)