⚙️ Moteur de Portefeuille — Modèle Mathématique

⬅️ Retour à l'aperçu des métriques de performance

💡 Aperçu

Cette page définit formellement le modèle mathématique sous-jacent au moteur de calcul de portefeuille de LibreFolio. Toutes les autres pages de métriques (NAV, Valeur Comptable, P&L de Période, PMP, Capital Déposé) se réfèrent à cette page pour leurs règles de calcul précises.

📐 1. Notation et Ensembles

Symbole	Signification
$V(u)$	Tous les courtiers visibles pour l'utilisateur $u$
$S \subseteq V(u)$	Périmètre des courtiers sélectionnés (filtrés)
$A$	Ensemble des actifs avec des positions
$C^*$	Devise cible
$[t_0, t_1]$	Cadre d'évaluation demandé
$q(a,b,t)$	Quantité de l'actif $a$ chez le courtier $b$ à la date $t$
$p(a,t)$	Prix d'évaluation de l'actif $a$ à la date $t$
$\mathrm{fx}(c_1, c_2, t)$	Taux de change de la devise $c_1$ vers $c_2$ à la date $t$

📐 2. Prix d'Évaluation

\[ p(a, t) = \begin{cases} p_{\text{mkt}}(a, t) & \text{si PriceHistory} \leq t \text{ existe} \\ p_{\text{buy}}(a, t) & \text{si le dernier BUY de } V(u) \text{ existe} \\ \varnothing & \text{sinon (exclu de la NAV)} \end{cases} \]

$p_{\text{mkt}}$ = comblement vers l'arrière (backward-fill) depuis PriceHistory (dernière clôture avec date $\leq t$)
$p_{\text{buy}}$ = prix unitaire du BUY le plus récent de $a$ parmi tous les courtiers de $V(u)$, avec date $\leq t$
Le PMP n'est jamais utilisé comme prix d'évaluation

📐 3. État de la Position

Pour chaque position $(a, b)$ avec $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) \]

Où $w(a,b,t)$ est le prix moyen pondéré (PMP) pour la position $(a,b)$ à la date $t$.

📐 4. Mise à jour itérative du PMP

Maintenu par position $(a,b)$ avec un état de pool $(\hat{q}, \hat{c})$ :

Acquisition (qty $> 0$, coût unitaire $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}}} \]

Réduction (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}} \]

Ordre de traitement

Pour une même date : les additions sont traitées avant les réductions. Cela garantit que la VENTE lit le PMP correct incluant les ACHATS du même jour.

📐 5. Agrégation du Portefeuille

\[ \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. Modèle de Cash à Trois Pools — Par Courtier $(K_b, R_b, W)$

Trois pools accumulateurs suivent la provenance du cash. $K$ et $R$ sont maintenus par courtier $b$ ; $W$ est global (sort entièrement du système).

Pool	Périmètre	Signification
$K_b$	Par courtier	Capital externe toujours présent chez le courtier $b$ sous forme de cash
$R_b$	Par courtier	Rendements générés toujours présents chez le courtier $b$ sous forme de cash
$W$	Global	Rendements ayant quitté le système (cachés, restaurables lors d'un nouveau dépôt)

Propriété clé

Un BUY sur le courtier $b_1$ ne peut consommer que $R_{b_1}$, jamais $R_{b_2}$. Le cash ne se déplace pas par magie entre les courtiers — seuls les transferts explicites déplacent les soldes des pools.

Règles de mise à jour (par transaction sur le courtier $b$, chronologique)

Icône & Type	Formules de Mise à Jour	Logique & Description
DÉPÔT $D > 0$	$r = \min(D,\, W)$ $R_b \mathrel{+}= r$ $W \mathrel{-}= r$ $K_b \mathrel{+}= D - r$	Restaure d'abord les rendements précédemment retirés du tracker global $W$, puis ajoute le reste au capital $K_b$.
RETRAIT $X > 0$	$k = \min(X,\, K_b)$ $K_b \mathrel{-}= k$ $\rho = \min(X - k,\, R_b)$ $R_b \mathrel{-}= \rho$ $W \mathrel{+}= \rho$	Consomme d'abord le capital $K_b$, puis déplace les rendements restants $\rho$ vers le tracker global $W$.
DIVIDENDE / INTÉRÊT $I > 0$	$R_b \mathrel{+}= I$	Les rendements augmentent directement le pool de rendements $R_b$.
FRAIS / TAXE $F > 0$	$R_b \mathrel{-}= F$ $\text{si } R_b < 0\text{: } K_b \mathrel{+}= R_b,\; R_b = 0$	Consomme d'abord les rendements $R_b$ ; si $R_b$ devient négatif, il est prélevé sur le capital $K_b$.
ACHAT $B > 0$	$\rho = \min(B,\, R_b)$ $R_b \mathrel{-}= \rho$ $K_b \mathrel{-}= (B - \rho)$	Consomme d'abord les rendements $R_b$, puis prélève le reste sur le capital $K_b$.
VENTE	$G = P - C$ $K_b \mathrel{+}= C$ $R_b \mathrel{+}= G$ $\text{si } R_b < 0\text{: } K_b \mathrel{+}= R_b, \quad R_b = 0$	La base de coût $C =
TRANSFERT DE LIQUIDITÉS (Interne, $s \to d$, $X > 0$)	Flux de départ ($s$) : $\rho = \min(X,\, R_s)$ $R_s \mathrel{-}= \rho$ $\kappa = X - \rho$ $K_s \mathrel{-}= \kappa$ Flux d'arrivée ($d$) : $K_d \mathrel{+}= \kappa$ $R_d \mathrel{+}= \rho$	Les transferts de liquidités internes déplacent les allocations de pools ($R_s \to R_d$, $K_s \to K_d$) proportionnellement au solde de départ. Le tracker global $W$ n'est jamais touché (le capital reste dans le système).

Si les dates de départ et d'arrivée diffèrent, le transfert est "en transit" : soustrait de $s$ au jour du départ, ajouté à $d$ au jour de l'arrivée. Entre ces dates, $\sum K_b + \sum R_b < \mathrm{Cash}_{\text{like}}$ du montant en transit — géré par une réconciliation proportionnelle.

Agrégation pour la sortie

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

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

Invariant de réconciliation

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

Une mise à l'échelle proportionnelle par courtier est appliquée si la dérive est $> 0.01$ (due aux arrondis FX ou au timing du transit).

📐 7. Contribution de Période

Pour la période $[t_0, t_1]$, par position $(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) \]

Ensemble des positions de contribution :

\[ \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}) \]

Les éléments non alloués (frais/revenus sans asset_id) sont groupés par courtier.

📐 8. Gain/Perte Réalisé

Lors d'une VENTE (SELL) de $|q_s|$ unités de la position $(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 \]

Où $w_{\text{pre}}$ est le PMP avant la réduction du pool (même valeur utilisée par la règle VENTE des 3-pools ci-dessus).

📐 9. Architecture Pre-Frame / Frame

Phase	Plage de dates	Calcule
Pre-frame	$[t_{\mathrm{first}},\ t_0)$	Cash, qty, PMP, pools — pas d'évaluation de marché
Frame	$[t_0,\ t_1]$	Quotidien complet : prix, FX, états des positions, états du portefeuille

Les transactions Pre-frame mettent à jour les accumulateurs (grand livre de cash, pools PMP, pools K/R/W) sans utiliser de données de prix ou de FX. Cela permet une mise en cache efficace basée sur des plages de dates.

📐 10. Métriques de Performance (Couche 2)

Calculées après les états quotidiens, lors d'une passe séparée :

Métrique	Formule	Référence
PnL Total	$\mathrm{NAV}(t) - \text{DepositedCapital}(t)$	Capital Déposé
PnL de Période	$\mathrm{NAV}(t_1) - \mathrm{NAV}(t_0) - \text{ECF}_{[t_0,t_1]}$	P&L de Période
TWRR	$\prod_i (1 + r_i) - 1$ (chaîne de sous-périodes)	TWRR
MWRR	XIRR résolvant $\sum \frac{CF_i}{(1+r)^{d_i/365}} = 0$	MWRR
ROI Simple	$(\mathrm{NAV} - \text{NetInvested}) / \text{NetInvested}$	ROI
Effet de Timing	$\text{MWRR}_{\text{cum}} - \text{TWRR}_{\text{cum}}$	Effet de Timing

🔗 Liens connexes

💼 NAV — évaluation instantanée
📖 Valeur Comptable — agrégat de la base de coût
📊 P&L de Période — gain/perte sur fenêtre avec contribution
💸 Capital Déposé — détails des 3-pools et exemples concrets
📈 PMP — méthode de coût itérative

Symbole	Signification
\(V(u)\)	Tous les courtiers visibles pour l'utilisateur \(u\)
\(S \subseteq V(u)\)	Périmètre des courtiers sélectionnés (filtrés)
\(A\)	Ensemble des actifs avec des positions
\(C^*\)	Devise cible
\([t_0, t_1]\)	Cadre d'évaluation demandé
\(q(a,b,t)\)	Quantité de l'actif \(a\) chez le courtier \(b\) à la date \(t\)
\(p(a,t)\)	Prix d'évaluation de l'actif \(a\) à la date \(t\)
\(\mathrm{fx}(c_1, c_2, t)\)	Taux de change de la devise \(c_1\) vers \(c_2\) à la date \(t\)

Icône & Type	Formules de Mise à Jour	Logique & Description
DÉPÔT \(D > 0\)	\(r = \min(D,\, W)\) \(R_b \mathrel{+}= r\) \(W \mathrel{-}= r\) \(K_b \mathrel{+}= D - r\)	Restaure d'abord les rendements précédemment retirés du tracker global \(W\), puis ajoute le reste au capital \(K_b\).
RETRAIT \(X > 0\)	\(k = \min(X,\, K_b)\) \(K_b \mathrel{-}= k\) \(\rho = \min(X - k,\, R_b)\) \(R_b \mathrel{-}= \rho\) \(W \mathrel{+}= \rho\)	Consomme d'abord le capital \(K_b\), puis déplace les rendements restants \(\rho\) vers le tracker global \(W\).
DIVIDENDE / INTÉRÊT \(I > 0\)	\(R_b \mathrel{+}= I\)	Les rendements augmentent directement le pool de rendements \(R_b\).
FRAIS / TAXE \(F > 0\)	\(R_b \mathrel{-}= F\) \(\text{si } R_b < 0\text{: } K_b \mathrel{+}= R_b,\; R_b = 0\)	Consomme d'abord les rendements \(R_b\) ; si \(R_b\) devient négatif, il est prélevé sur le capital \(K_b\).
ACHAT \(B > 0\)	\(\rho = \min(B,\, R_b)\) \(R_b \mathrel{-}= \rho\) \(K_b \mathrel{-}= (B - \rho)\)	Consomme d'abord les rendements \(R_b\), puis prélève le reste sur le capital \(K_b\).
VENTE	\(G = P - C\) \(K_b \mathrel{+}= C\) \(R_b \mathrel{+}= G\) \(\text{si } R_b < 0\text{: } K_b \mathrel{+}= R_b, \quad R_b = 0\)	La base de coût $C =
TRANSFERT DE LIQUIDITÉS (Interne, \(s \to d\), \(X > 0\))	Flux de départ (\(s\)) : \(\rho = \min(X,\, R_s)\) \(R_s \mathrel{-}= \rho\) \(\kappa = X - \rho\) \(K_s \mathrel{-}= \kappa\) Flux d'arrivée (\(d\)) : \(K_d \mathrel{+}= \kappa\) \(R_d \mathrel{+}= \rho\)	Les transferts de liquidités internes déplacent les allocations de pools (\(R_s \to R_d\), \(K_s \to K_d\)) proportionnellement au solde de départ. Le tracker global \(W\) n'est jamais touché (le capital reste dans le système).