# Perpetual Position Calculator - Detailed Operation Guide

This document outlines the precise calculations and logic used within the Perpetual Position Calculator application.

## 1. Core State Variables

The calculator operates based on two main sets of inputs:
1.  **Current Position:** Size, Entry Price, Mark Price, Current Margin, Leverage, Position Type (Long/Short).
2.  **Additional Inputs:** Additional Margin, Additional Size, Add at Price.

## 2. Current Margin and Leverage Relationship

The calculator assumes a cross-margin mode where the margin is determined by the desired leverage.

*   **Notional Value (V):** Current Position Size * Entry Price
*   **Leverage (L):** Notional Value / Current Margin

When the user changes the **Leverage (L)** input, the **Current Margin (M_current)** is automatically recalculated:
M_current = (Current Position Size * Entry Price) / L

## 3. Calculation of New Metrics

The new metrics are calculated based on the combined position (Original + Additional).

### 3.1. Total Position Size (S_new)
S_new = Original Size + Additional Size

### 3.2. Total Margin (M_total)
M_total = Current Margin + Additional Margin

### 3.3. New Average Entry Price (E_avg)
The average entry price is a weighted average based on the notional value of each component:
E_avg = [(Original Size * Original Entry Price) + (Additional Size * Add at Price)] / S_new

### 3.4. New Liquidation Price (L_new)
The liquidation price calculation uses a simplified cross-margin model, assuming a maintenance margin rate (MMR) of zero for simplicity, which is common for basic calculator tools.

*   **For a LONG Position:**
    L_new = E_avg - (M_total / S_new)

*   **For a SHORT Position:**
    L_new = E_avg + (M_total / S_new)

### 3.5. New Unrealized PnL (PnL_new)
PnL_new = (Mark Price - E_avg) * S_new * Direction

Where Direction is:
*   +1 for Long positions
*   -1 for Short positions

### 3.6. Margin Ratio (R_margin)
The Margin Ratio is calculated as Equity divided by Notional Value. Equity is Total Margin plus Unrealized PnL.
*   **Total Notional Value (V_total):** S_new * E_avg
*   **Total Equity (E_total):** M_total + PnL_new
*   R_margin = (E_total / V_total) * 100%

### 3.7. Effective Leverage (L_effective)
L_effective = V_total / M_total

### 3.8. Distance to Liquidation (D_liq)
D_liq measures the percentage distance the Mark Price must move before hitting the New Liquidation Price.

D_liq = [(Mark Price - L_new) / Mark Price] * 100% * Direction

Where Direction is:
*   +1 for Long positions (price must fall)
*   -1 for Short positions (price must rise)