Skip to content

📊 Period PnL (Profit and Loss)

💡 What is Period PnL?

The absolute monetary gain or loss generated by your portfolio within \([t_0, t_1]\), adjusted for external cash flows.

🧮 Formula

\[ \boxed{\mathrm{PnL}_{\text{period}} = \mathrm{NAV}(t_1)-\mathrm{NAV}(t_0)-\Delta \mathrm{CapitalBaseline}_{[t_0,t_1]}} \]

The baseline delta comes from cumulative_external_cash_flow, so it includes cash flows and priced in-kind ADJUSTMENT/TRANSFER capital.

🧮 Decomposition

\[ \mathrm{PnL}_{\text{period}} = \Delta\mathrm{UGL} + \mathrm{Realized} + \mathrm{Income} - \mathrm{FeesTaxes} + \mathrm{Other} \]
Component Definition
\(\Delta\mathrm{UGL}\) Change in unrealized gain/loss over the period — for assets priced in another currency, including the exchange-rate effect on their historical cost
Realized Sum of (sell proceeds − historical cost of the units sold) for SELLs in period; proceeds are converted at the sale date
Income DIVIDEND + INTEREST in period
FeesTaxes FEE + TAX in period
Other What closes the identity: the exchange result on cash held in another currency (FX on cash) plus a residual

Other is computed as:

\[ \mathrm{Other} = \mathrm{PnL}_{\text{period}} - \Delta\mathrm{UGL} - \mathrm{Realized} - \mathrm{Income} + \mathrm{FeesTaxes} \]

Because the cost basis keeps its historical exchange rates (see Book Value), the effect of exchange rates on foreign assets is part of \(\Delta\mathrm{UGL}\), not of Other. Cash held in another currency is different: NAV and Book both value it at each day's rate, so its exchange-rate effect cancels in the unrealized gain/loss and is not in \(\Delta\mathrm{UGL}\). It is the first part of Other, the FX on cash of each broker \(b\), which the Period view shows per broker:

\[ \mathrm{Other} = \sum_{b \in S} \mathrm{FXonCash}_b + \mathrm{Residual} \]

The residual holds what neither the four components nor the exchange result on cash can see:

  • the exchange-rate move of cash while it travels between two brokers: in transit, it belongs to no broker's balance;
  • the cost of a currency exchange, at one broker or across two: −1,000 USD worth €920 at the day's rate, exchanged into +€900, gives −€20, which is neither a fee nor a sale;
  • the value of assets travelling between two brokers on a boundary day;
  • a sale left out of Realized because its proceeds could not be converted or its position's cost is incomplete.

💵 FX on Cash

For each broker \(b\) holding cash in a currency other than \(C^*\), over the period \((t_0, t_1]\), \(t_0\) being the opening state:

\[ \mathrm{FXonCash}_b = \sum_{c \neq C^*} \Bigl[N_{b,c}(t_1)\,\mathrm{fx}(c, C^*, t_1) - N_{b,c}(t_0)\,\mathrm{fx}(c, C^*, t_0)\Bigr] - \sum_{\substack{m \in (t_0, t_1] \\ \mathrm{ccy}(m) \neq C^*}} s_m \cdot \mathrm{amount}_m \cdot \mathrm{fx}(\mathrm{ccy}(m), C^*, d_m) \]

\(N_{b,c}(t)\) is the balance \(b\) holds in currency \(c\) on \(t\), scaled by the broker's share, and \(\mathrm{fx}\) the latest rate on or before the day. The second sum runs over \(b\)'s movements in a foreign currency dated in the period: each amount, scaled by the share \(s_m\), at the rate of its own date \(d_m\). The first term is the change in value of the foreign cash, the second what the movements brought in or took out: the difference is what the exchange rates did to the cash the broker held. It equals the exchange results the engine books on the period's rate-change days (Portfolio Engine — §6). Cash in \(C^*\) has none.

Example: dollars at a broker on a euro dashboard

A broker holds 1,000 USD for the whole period while the rate goes from 0.90 to 0.92 EUR per USD:

\[ \mathrm{FXonCash} = 1{,}000 \times 0.92 - 1{,}000 \times 0.90 = +20 \text{ EUR} \]

With a deposit of 500 USD in the middle of the period at 0.91, and 0.92 at the end:

\[ \mathrm{FXonCash} = 1{,}500 \times 0.92 - 1{,}000 \times 0.90 - 500 \times 0.91 = 1{,}380 - 900 - 455 = +25 \text{ EUR} \]

The deposit entered the capital at €455; the +€25 is what the dollars gained against the euro while the broker held them.

💱 Unrealized Change by Currency

\(\Delta\mathrm{UGL}\) is split by the currency \(A\) the assets are priced in. For the positions in currency \(A\) on day \(t\), let

Symbol Meaning
\(\mathrm{MV}_A(t)\) Their market value in \(C^*\), at the day's price and rate
\(\mathrm{Cost}^{A}_A(t)\) Their historical cost in \(A\)
\(\mathrm{Cost}^{*}_A(t)\) Their historical cost in \(C^*\)
\(r_A(t) = \mathrm{fx}(A, C^*, t)\) The day's exchange rate

Each acquisition's cost in \(A\) comes from its cost in \(C^*\) at the acquisition date, \(c^{A} = c^{*} \cdot \mathrm{fx}(C^*, A, d)\) (or the amount paid, when paid in \(A\)). The unrealized gain/loss then splits exactly into an asset effect and an exchange-rate effect:

\[ E^{\text{asset}}_A(t) = \mathrm{MV}_A(t) - \mathrm{Cost}^{A}_A(t)\, r_A(t) \]
\[ E^{\text{fx}}_A(t) = \mathrm{Cost}^{A}_A(t)\, r_A(t) - \mathrm{Cost}^{*}_A(t) \]
\[ E^{\text{asset}}_A(t) + E^{\text{fx}}_A(t) = \mathrm{MV}_A(t) - \mathrm{Cost}^{*}_A(t) = \mathrm{UGL}_A(t) \]

For a mark quoted in \(A\), \(\mathrm{MV}_A(t) = \frac{q}{qbq} \cdot \mathrm{mark}_A(t) \cdot r_A(t)\), so the asset effect is the assets' own change in their currency, translated at the day's rate: \(E^{\text{asset}}_A(t) = \bigl(\frac{q}{qbq} \cdot \mathrm{mark}_A(t) - \mathrm{Cost}^{A}_A(t)\bigr)\, r_A(t)\). The exchange-rate effect is zero on the day of each purchase. For \(A = C^*\), \(r = 1\) and \(\mathrm{Cost}^{A} = \mathrm{Cost}^{*}\): the exchange-rate effect vanishes, and assets already in the report currency have an asset effect only.

A position in a currency \(A \neq C^*\) that cannot be split on day \(t\) — no market value, no rate \(r_A(t)\), or a cost incomplete in either currency — adds its whole \(\mathrm{MV} - \mathrm{Cost}^{*}\) (with \(\mathrm{MV} = 0\) when it has no market value) to an unsplit part \(E^{\text{unsplit}}_A(t)\) instead. Positions in \(C^*\) always count in the asset effect.

The period rows are the changes between the period's two boundary states — the last state on or before \(t_0\) (zero if there is none) and the state at \(t_1\) —, the same two states as \(\Delta\mathrm{UGL}\):

\[ \Delta E^{k}_A = E^{k}_A(t_1) - E^{k}_A(t_0), \qquad k \in \{\text{asset}, \text{fx}, \text{unsplit}\} \]
\[ \sum_{A}\ \sum_{k} \Delta E^{k}_A = \Delta\mathrm{UGL} \quad \text{exactly} \]
Example: a US ETF on a euro dashboard

10 units bought for €400 when they were worth 500 USD, so \(\mathrm{Cost}^{*} = 400\) EUR and \(\mathrm{Cost}^{A} = 500\) USD.

Day Value in USD \(r_{USD}\) MV in EUR \(E^{\text{asset}}\) \(E^{\text{fx}}\) \(\mathrm{UGL}\)
\(t_0\) 520 USD 0.78 405.60 \((520-500) \times 0.78 = 15.60\) \(500 \times 0.78 - 400 = -10.00\) 5.60
\(t_1\) 550 USD 0.75 412.50 \((550-500) \times 0.75 = 37.50\) \(500 \times 0.75 - 400 = -25.00\) 12.50
\[ \Delta E^{\text{asset}} = +21.90, \qquad \Delta E^{\text{fx}} = -15.00, \qquad \Delta\mathrm{UGL} = +6.90 \text{ EUR} \]

The ETF gained in dollars (+€21.90), the dollar lost ground against the euro (−€15.00): together, the +€6.90 of the period's unrealized change.

🎯 Per-Asset Contribution

For each position \((a,b)\):

\[ \mathrm{PnL}(a,b) = \Delta\mathrm{UGL}(a,b) + \mathrm{Realized}(a,b) + \mathrm{Income}(a,b) - \mathrm{FeesTaxes}(a,b) \]

The position set includes all activity in the period:

\[ \mathcal{P} = \text{positions with BUY/SELL/ADJUSTMENT/TRANSFER activity or boundary quantity} \]

Annualized period return clamps its window start to the later of the requested start and the oldest open lot date. It uses \(|\mathrm{StartValue}|\) as annualization base, falling back to end cost basis for positions opened mid-period. See Net Annualized Return.

🔗 See Portfolio Engine — §7 Period Contribution for details.

📝 Example

  • NAV at \(t_0\): €27,000
  • Capital baseline increase in period: €1,000
  • NAV at \(t_1\): €33,000
\[ \mathrm{PnL} = 33\,000 - 27\,000 - 1\,000 = +5\,000 \text{ EUR} \]