# `DeltaCalc.PositionCalculator`
[🔗](https://github.com/ZenHive/delta_calc/blob/v0.3.0/lib/delta_calc/position_calculator.ex#L1)

Core position sizing calculations for risk management and leverage planning.

Handles position size, effective leverage, safety analysis, allocation breakdowns,
and liquidation price analysis using Decimal arithmetic throughout.

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `calculate_position` | 1 | Compute position size, leverage, safety, and allocation breakdown. | `params: value` |

# `calculation_result`

```elixir
@type calculation_result() :: %{
  allocation: map(),
  position: map(),
  effective_leverage: Decimal.t(),
  leverage_to_aum: Decimal.t(),
  safety: map(),
  mmr_info: map()
}
```

# `params`

```elixir
@type params() :: %{
  aum: Decimal.t(),
  side: :long | :short,
  entry_price: Decimal.t(),
  subaccount_allocation: Decimal.t(),
  initial_position_pct: Decimal.t(),
  black_swan_pct: Decimal.t(),
  ui_leverage: Decimal.t(),
  mmr_rate: Decimal.t(),
  mark_buffer: Decimal.t()
}
```

# `calculate_position`

```elixir
@spec calculate_position(params()) :: calculation_result() | {:error, atom()}
```

Performs comprehensive position calculations based on validated parameters.

## Parameters
- `params`: Map containing validated parameters including:
  - `:aum` - Assets Under Management (Decimal)
  - `:side` - Position side atom (:long, :short)
  - `:entry_price` - Entry price (Decimal)
  - `:subaccount_allocation` - Subaccount allocation amount (Decimal)
  - `:initial_position_pct` - Initial position percentage as decimal (0-1)
  - `:black_swan_pct` - Black swan threshold as decimal (0-1)
  - `:ui_leverage` - UI leverage setting (Decimal)
  - `:mmr_rate` - Minimum margin requirement rate (Decimal)
  - `:mark_buffer` - Mark price buffer (Decimal)

## Returns
A map containing:
- `:allocation` - Allocation breakdown with subaccount equity, position, and reserves
- `:position` - Position details with notional value and effective leverage
- `:effective_leverage` - Overall effective leverage
- `:leverage_to_aum` - Position size as percentage of total AUM
- `:safety` - Safety analysis with liquidation and black swan metrics
- `:mmr_info` - MMR rate information for display

## Examples

    params = %{
      aum: Decimal.new("10000"),
      side: :long,
      entry_price: Decimal.new("3000"),
      subaccount_allocation: Decimal.new("100"),
      initial_position_pct: Decimal.new("0.5"),
      black_swan_pct: Decimal.new("0.15"),
      ui_leverage: Decimal.new("2"),
      mmr_rate: Decimal.new("0.005"),
      mark_buffer: Decimal.new("0.001")
    }

    calculate_position(params)

---

*Consult [api-reference.md](api-reference.md) for complete listing*