⚙️ Portfolio Engine — Modello Matematico

⬅️ Torna a Panoramica Metriche di Performance

💡 Panoramica

Questa pagina definisce formalmente il modello matematico alla base del motore di calcolo del portafoglio di LibreFolio. Tutte le altre pagine relative alle metriche (NAV, Book Value, Period P&L, PMC, Deposited Capital) fanno riferimento a questa pagina per le loro precise regole di computazione.

📐 1. Notazione e Insiemi

Simbolo	Significato
$V(u)$	Tutti i broker visibili all'utente $u$
$S \subseteq V(u)$	Ambito dei broker selezionati (filtrati)
$A$	Insieme degli asset con posizioni
$C^*$	Valuta target
$[t_0, t_1]$	Frame di valutazione richiesto
$q(a,b,t)$	Quantità dell'asset $a$ presso il broker $b$ alla data $t$
$p(a,t)$	Prezzo di valutazione dell'asset $a$ alla data $t$
$\mathrm{fx}(c_1, c_2, t)$	Tasso di cambio dalla valuta $c_1$ alla $c_2$ alla data $t$

📐 2. Prezzo di Valutazione

\[ p(a, t) = \begin{cases} p_{\text{mkt}}(a, t) & \text{se esiste un PriceHistory} \leq t \\ p_{\text{buy}}(a, t) & \text{se esiste l'ultimo BUY da } V(u) \\ \varnothing & \text{altrimenti (escluso dal NAV)} \end{cases} \]

$p_{\text{mkt}}$ = riempimento a ritroso (backward-fill) da PriceHistory (ultima chiusura con data $\leq t$)
$p_{\text{buy}}$ = prezzo unitario dell'acquisto (BUY) più recente di $a$ tra tutti i broker in $V(u)$, con data $\leq t$
Il PMC non viene mai utilizzato come prezzo di valutazione

📐 3. Stato della Posizione

Per ogni posizione $(a, b)$ con $q(a,b,t) > 0$:

\[ \mathrm{MV}(a,b,t) = q(a,b,t) \cdot p(a,t) \cdot \mathrm{fx}\bigl(\mathrm{ccy}_p, C^*, t\bigr) \]

\[ \mathrm{CB}(a,b,t) = q(a,b,t) \cdot w(a,b,t) \cdot \mathrm{fx}\bigl(\mathrm{ccy}_w, C^*, t\bigr) \]

\[ \mathrm{UGL}(a,b,t) = \mathrm{MV}(a,b,t) - \mathrm{CB}(a,b,t) \]

Dove $w(a,b,t)$ è il prezzo medio di carico (PMC) per la posizione $(a,b)$ alla data $t$.

📐 4. Aggiornamento Iterativo PMC

Mantenuto per singola posizione $(a,b)$ con stato del pool $(\hat{q}, \hat{c})$:

Acquisizione (qty $> 0$, costo unitario $u$):

\[ \hat{q}_{\text{new}} = \hat{q} + q_{\text{tx}}, \quad \hat{c}_{\text{new}} = \hat{c} + u \cdot q_{\text{tx}}, \quad w = \frac{\hat{c}_{\text{new}}}{\hat{q}_{\text{new}}} \]

Riduzione (qty $< 0$):

\[ w_{\text{pre}} = \frac{\hat{c}}{\hat{q}}, \quad \hat{q}_{\text{new}} = \hat{q} - |q_{\text{tx}}|, \quad \hat{c}_{\text{new}} = \hat{q}_{\text{new}} \cdot w_{\text{pre}} \]

Ordinamento

Entro la stessa data: le aggiunte vengono elaborate prima delle riduzioni. Questo assicura che l'operazione di SELL legga il PMC corretto, inclusi gli ACQUISTI dello stesso giorno.

📐 5. Aggregazione del Portafoglio

\[ \mathrm{MV}(t) = \sum_{(a,b) \in S} \mathrm{MV}(a,b,t) \]

\[ \mathrm{NAV}(t) = \mathrm{MV}(t) + \mathrm{Cash}(t) + \mathrm{InTransit}(t) \]

\[ \mathrm{Book}(t) = \mathrm{OCB}(t) + \mathrm{Cash}(t) + \mathrm{InTransitBook}(t) \]

\[ \mathrm{UGL}(t) = \mathrm{NAV}(t) - \mathrm{Book}(t) \]

📐 6. Modello Cash a Tre Pool — Per Broker $(K_b, R_b, W)$

Tre pool di accumulo tracciano la provenienza della liquidità. $K$ e $R$ sono mantenuti per broker $b$; $W$ è globale (esce completamente dal sistema).

Pool	Ambito	Significato
$K_b$	Per broker	Capitale esterno ancora presente nel broker $b$ come cash
$R_b$	Per broker	Rendimenti generati ancora presenti nel broker $b$ come cash
$W$	Globale	Rendimenti che hanno lasciato il sistema (nascosti, recuperabili al ri-deposito)

Proprietà chiave

Un acquisto (BUY) sul broker $b_1$ può consumare solo $R_{b_1}$, mai $R_{b_2}$. La liquidità non si "teletrasporta" tra i broker — solo i trasferimenti espliciti spostano i saldi dei pool.

Regole di aggiornamento (per transazione sul broker $b$, cronologiche)

Icona e Tipo	Formule di Aggiornamento	Logica e Descrizione
DEPOSITO $D > 0$	$r = \min(D,\, W)$ $R_b \mathrel{+}= r$ $W \mathrel{-}= r$ $K_b \mathrel{+}= D - r$	Ripristina i rendimenti precedentemente prelevati dal tracker globale $W$ prima di aggiungere il restante al capitale $K_b$.
PRELIEVO $X > 0$	$k = \min(X,\, K_b)$ $K_b \mathrel{-}= k$ $\rho = \min(X - k,\, R_b)$ $R_b \mathrel{-}= \rho$ $W \mathrel{+}= \rho$	Consuma prima il capitale $K_b$, poi sposta i rendimenti rimanenti $\rho$ nel tracker globale $W$.
DIVIDENDO / INTERESSE $I > 0$	$R_b \mathrel{+}= I$	I rendimenti incrementano direttamente il pool dei rendimenti $R_b$.
COMMISSIONE / IMPOSTA $F > 0$	$R_b \mathrel{-}= F$ $\text{se } R_b < 0\text{: } K_b \mathrel{+}= R_b,\; R_b = 0$	Consuma prima i rendimenti $R_b$; se $R_b$ diventa negativo, attinge dal capitale $K_b$.
ACQUISTO $B > 0$	$\rho = \min(B,\, R_b)$ $R_b \mathrel{-}= \rho$ $K_b \mathrel{-}= (B - \rho)$	Consuma prima i rendimenti $R_b$, poi preleva il resto dal capitale $K_b$.
VENDITA	$G = P - C$ $K_b \mathrel{+}= C$ $R_b \mathrel{+}= G$ $\text{se } R_b < 0\text{: } K_b \mathrel{+}= R_b, \quad R_b = 0$	Il costo di base $C =
TRASFERIMENTO DI LIQUIDITÀ (Interno, $s \to d$, $X > 0$)	Tratta di uscita ($s$): $\rho = \min(X,\, R_s)$ $R_s \mathrel{-}= \rho$ $\kappa = X - \rho$ $K_s \mathrel{-}= \kappa$ Tratta di arrivo ($d$): $K_d \mathrel{+}= \kappa$ $R_d \mathrel{+}= \rho$	I trasferimenti interni di liquidità spostano le allocazioni dei pool ($R_s \to R_d$, $K_s \to K_d$) in proporzione al saldo di partenza. Il tracker globale $W$ non viene mai toccato (il capitale rimane nel sistema).

Se le date di uscita e arrivo differiscono, il trasferimento è in transito (in-transit): sottratto da $s$ nel giorno di partenza, aggiunto a $d$ nel giorno di arrivo. Tra queste date, $\sum K_b + \sum R_b < \mathrm{Cash}_{\text{like}}$ per l'importo in transito — gestito tramite riconciliazione proporzionale.

Aggregazione per l'output

\[ \mathrm{CashFromCapital}(t) = \sum_{b \in S} K_b(t) \]

\[ \mathrm{CashFromReturns}(t) = \sum_{b \in S} R_b(t) \]

Invariante di riconciliazione

\[ \mathrm{Cash}_{\text{like}}(t) \approx \sum_{b \in S} K_b(t) + \sum_{b \in S} R_b(t) \]

Viene applicato uno scaling proporzionale per broker se il drift è $> 0.01$ (dovuto ad arrotondamenti FX o timing in-transit).

📐 7. Contributo di Periodo

Per il periodo $[t_0, t_1]$, per posizione $(a,b)$:

\[ \Delta\mathrm{UGL}(a,b) = \mathrm{UGL}(a,b,t_1) - \mathrm{UGL}(a,b,t_0) \]

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

Insieme delle posizioni che contribuiscono:

\[ \mathcal{P} = \mathcal{P}(t_0) \cup \mathcal{P}(t_1) \cup \mathrm{keys}(\text{Realized}) \cup \mathrm{keys}(\text{Income}) \cup \mathrm{keys}(\text{Fees}) \]

Le voci non allocate (commissioni/redditi senza asset_id) sono raggruppate per broker.

📐 8. Guadagno/Perdita Realizzata (Realized Gain/Loss)

Su SELL di $|q_s|$ unità dalla posizione $(a,b)$:

\[ C = |q_s| \cdot w_{\text{pre}}(a,b) \cdot \mathrm{fx}(\mathrm{ccy}_w, C^*, t) \]

\[ \mathrm{Realized} = P_{\text{sell}} - C \]

Dove $w_{\text{pre}}$ è il PMC prima della riduzione del pool (stesso valore usato dalla regola SELL a 3 pool sopra).

📐 9. Architettura Pre-Frame / Frame

Fase	Intervallo date	Calcola
Pre-frame	$[t_{\mathrm{first}},\ t_0)$	Cash, qty, PMC, pool — nessuna valutazione di mercato
Frame	$[t_0,\ t_1]$	Completo giornaliero: prezzi, FX, stati delle posizioni, stati del portafoglio

Le transazioni nel pre-frame aggiornano gli accumulatori (libro cassa, pool PMC, modello a 3 pool K/R/W) senza consumare dati di prezzo o FX. Ciò consente un caching efficiente basato su range.

📐 10. Metriche di Performance (Layer 2)

Calcolate dopo gli stati giornalieri, come passaggio separato:

Metrica	Formula	Riferimento
PnL Totale	$\mathrm{NAV}(t) - \text{DepositedCapital}(t)$	Deposited Capital
PnL di Periodo	$\mathrm{NAV}(t_1) - \mathrm{NAV}(t_0) - \text{ECF}_{[t_0,t_1]}$	Period P&L
TWRR	$\prod_i (1 + r_i) - 1$ (catena di sotto-periodi)	TWRR
MWRR	XIRR risolvendo $\sum \frac{CF_i}{(1+r)^{d_i/365}} = 0$	MWRR
Simple ROI	$(\mathrm{NAV} - \text{NetInvested}) / \text{NetInvested}$	ROI
Timing Effect	$\text{MWRR}_{\text{cum}} - \text{TWRR}_{\text{cum}}$	Timing Effect

🔗 Correlati

💼 NAV — valutazione istantanea (snapshot)
📖 Book Value — aggregato del costo di base
📊 Period P&L — guadagni/perdite in una finestra temporale con contributo
💸 Deposited Capital — dettagli sui 3 pool ed esempi pratici
📈 PMC — metodo di costo iterativo

Simbolo	Significato
\(V(u)\)	Tutti i broker visibili all'utente \(u\)
\(S \subseteq V(u)\)	Ambito dei broker selezionati (filtrati)
\(A\)	Insieme degli asset con posizioni
\(C^*\)	Valuta target
\([t_0, t_1]\)	Frame di valutazione richiesto
\(q(a,b,t)\)	Quantità dell'asset \(a\) presso il broker \(b\) alla data \(t\)
\(p(a,t)\)	Prezzo di valutazione dell'asset \(a\) alla data \(t\)
\(\mathrm{fx}(c_1, c_2, t)\)	Tasso di cambio dalla valuta \(c_1\) alla \(c_2\) alla data \(t\)

Icona e Tipo	Formule di Aggiornamento	Logica e Descrizione
DEPOSITO \(D > 0\)	\(r = \min(D,\, W)\) \(R_b \mathrel{+}= r\) \(W \mathrel{-}= r\) \(K_b \mathrel{+}= D - r\)	Ripristina i rendimenti precedentemente prelevati dal tracker globale \(W\) prima di aggiungere il restante al capitale \(K_b\).
PRELIEVO \(X > 0\)	\(k = \min(X,\, K_b)\) \(K_b \mathrel{-}= k\) \(\rho = \min(X - k,\, R_b)\) \(R_b \mathrel{-}= \rho\) \(W \mathrel{+}= \rho\)	Consuma prima il capitale \(K_b\), poi sposta i rendimenti rimanenti \(\rho\) nel tracker globale \(W\).
DIVIDENDO / INTERESSE \(I > 0\)	\(R_b \mathrel{+}= I\)	I rendimenti incrementano direttamente il pool dei rendimenti \(R_b\).
COMMISSIONE / IMPOSTA \(F > 0\)	\(R_b \mathrel{-}= F\) \(\text{se } R_b < 0\text{: } K_b \mathrel{+}= R_b,\; R_b = 0\)	Consuma prima i rendimenti \(R_b\); se \(R_b\) diventa negativo, attinge dal capitale \(K_b\).
ACQUISTO \(B > 0\)	\(\rho = \min(B,\, R_b)\) \(R_b \mathrel{-}= \rho\) \(K_b \mathrel{-}= (B - \rho)\)	Consuma prima i rendimenti \(R_b\), poi preleva il resto dal capitale \(K_b\).
VENDITA	\(G = P - C\) \(K_b \mathrel{+}= C\) \(R_b \mathrel{+}= G\) \(\text{se } R_b < 0\text{: } K_b \mathrel{+}= R_b, \quad R_b = 0\)	Il costo di base $C =
TRASFERIMENTO DI LIQUIDITÀ (Interno, \(s \to d\), \(X > 0\))	Tratta di uscita (\(s\)): \(\rho = \min(X,\, R_s)\) \(R_s \mathrel{-}= \rho\) \(\kappa = X - \rho\) \(K_s \mathrel{-}= \kappa\) Tratta di arrivo (\(d\)): \(K_d \mathrel{+}= \kappa\) \(R_d \mathrel{+}= \rho\)	I trasferimenti interni di liquidità spostano le allocazioni dei pool (\(R_s \to R_d\), \(K_s \to K_d\)) in proporzione al saldo di partenza. Il tracker globale \(W\) non viene mai toccato (il capitale rimane nel sistema).