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

Effective-leverage and position aggregation calculations.

All functions use `Decimal` arithmetic and preserve the active `Decimal.Context` precision.

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `multi_leg_position` | 4 | Calculate side-aware multi-leg cross-margin position aggregates. | `legs: value`, `current_price: value`, `initial_equity: value`, `side: value` |
| `position` | 5 | Calculate position notional and effective leverage. | `sub_eq: value`, `init_margin_pct: value`, `ui_lev: value`, `entry: value`, `side: value` |
| `leverage_to_aum` | 2 | Calculate position notional as a fraction of total AUM. | `notional: value`, `total_aum: value` |
| `effective_leverage` | 2 | Calculate effective leverage from notional and wallet equity. | `notional: value`, `wallet_equity: value` |

# `decimal_result`

```elixir
@type decimal_result() :: Decimal.t() | {:error, atom()}
```

# `effective_leverage`

```elixir
@spec effective_leverage(Decimal.t(), Decimal.t()) :: decimal_result()
```

Calculate effective leverage from notional and wallet equity.

## Parameters

  * `notional` - Position notional value as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `wallet_equity` - Wallet/subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)

## Returns

Effective leverage (notional / equity), or \{:error, :non_positive_wallet_equity\} (`decimal`)

```elixir
# descripex:contract
%{
  params: %{
    notional: %{
      description: "Position notional value as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    wallet_equity: %{
      description: "Wallet/subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    }
  },
  returns: %{
    type: :decimal,
    description: "Effective leverage (notional / equity), or {:error, :non_positive_wallet_equity}"
  }
}
```

# `leverage_to_aum`

```elixir
@spec leverage_to_aum(Decimal.t(), Decimal.t()) :: decimal_result()
```

Calculate position notional as a fraction of total AUM.

## Parameters

  * `notional` - Position notional value as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `total_aum` - Total assets under management as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)

## Returns

Exposure ratio (notional / AUM), or \{:error, :non_positive_total_aum\} (`decimal`)

```elixir
# descripex:contract
%{
  params: %{
    notional: %{
      description: "Position notional value as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    total_aum: %{
      description: "Total assets under management as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    }
  },
  returns: %{
    type: :decimal,
    description: "Exposure ratio (notional / AUM), or {:error, :non_positive_total_aum}"
  }
}
```

# `multi_leg_position`

```elixir
@spec multi_leg_position([map()], Decimal.t(), Decimal.t(), :long | :short) :: map()
```

Calculate side-aware multi-leg cross-margin position aggregates.

## Parameters

  * `legs` - List of position legs whose :entry and :notional fields are canonical decimal strings; native Elixir callers may also pass Decimal or integer. (value)
  * `current_price` - Current market price as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `initial_equity` - Starting subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `side` - Position side (:long or :short) used for unrealized PnL (default: `:long`, value)

## Returns

Map with total_notional, avg_entry, unrealized_pnl, current_equity, effective_leverage (`map`)

```elixir
# descripex:contract
%{
  params: %{
    side: %{
      default: :long,
      description: "Position side (:long or :short) used for unrealized PnL",
      kind: :value,
      schema: %{"enum" => ["long", "short"], "type" => "string"}
    },
    legs: %{
      description: "List of position legs whose :entry and :notional fields are canonical decimal strings; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{
        "items" => %{
          "additionalProperties" => false,
          "properties" => %{
            "entry" => %{"type" => "string"},
            "notional" => %{"type" => "string"}
          },
          "required" => ["entry", "notional"],
          "type" => "object"
        },
        "type" => "array"
      }
    },
    current_price: %{
      description: "Current market price as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    initial_equity: %{
      description: "Starting subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    }
  },
  returns: %{
    type: :map,
    description: "Map with total_notional, avg_entry, unrealized_pnl, current_equity, effective_leverage"
  }
}
```

# `position`

```elixir
@spec position(Decimal.t(), Decimal.t(), Decimal.t(), Decimal.t(), :long | :short) ::
  map()
```

Calculate position notional and effective leverage.

## Parameters

  * `sub_eq` - Subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `init_margin_pct` - Initial margin percentage (0-1) as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `ui_lev` - UI leverage (1-125) as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `entry` - Entry price as a canonical decimal string; native Elixir callers may also pass Decimal or integer. (value)
  * `side` - Position side (:long or :short) (value)

## Returns

Map with :notional and :eff_lev Decimal fields (`map`)

```elixir
# descripex:contract
%{
  params: %{
    entry: %{
      description: "Entry price as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    side: %{
      description: "Position side (:long or :short)",
      kind: :value,
      schema: %{"enum" => ["long", "short"], "type" => "string"}
    },
    sub_eq: %{
      description: "Subaccount equity as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    init_margin_pct: %{
      description: "Initial margin percentage (0-1) as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    },
    ui_lev: %{
      description: "UI leverage (1-125) as a canonical decimal string; native Elixir callers may also pass Decimal or integer.",
      kind: :value,
      schema: %{"type" => "string"}
    }
  },
  returns: %{
    type: :map,
    description: "Map with :notional and :eff_lev Decimal fields"
  }
}
```

---

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