FIN — Portefeuille & Monte-Carlo : simuler la BVC depuis le terminal

Ce projet est écrit en français : il porte sur la Bourse de Casablanca et s’adresse aux étudiants et investisseurs du marché marocain. Un résumé exécutif en anglais suit.

English summary. fin is an open-source bash toolkit (built on curl and jq) that lives inside the shell prompt and covers the Casablanca Stock Exchange natively. The one-minute screencast below (sped up ×2) shows the newest part of it: a portfolio builder and a Monte-Carlo engine, both callable as plain terminal commands. First, bvc prints the live Casablanca board (77 listed tickers via TradingView’s CSEMA scan, plus the sector market-cap bars and the FIN_BVC watchlist). Then portfolio add YirPort AKT 30, ... ATW 50, ... STM 20 build a weighted basket in ~/.fin/portfolios/YirPort.tsv. Finally, mc YirPort --years 2 --sims 10000 --initial 10000 pulls the daily history of each holding, block-bootstraps their joint returns, and reports the result as a summary table and a histogram: a mean terminal value of $16,234 (+62.3 %) against a $10,000 start, a median of $15,719, a 95% VaR of +3.2 % and a 95% CVaR of −7.3 %. The run prints a seed, so the exact simulation can be replayed. It is the same Monte-Carlo and VaR methodology as the Casablanca Quant Framework project — compressed from a Jupyter/Makefile stack into a single command. Source: https://github.com/yirvisom/fin-terminal.

La démonstration en une minute

Ce qui suit n’est pas une capture d’écran figée : c’est un enregistrement réel du terminal, du premier coup de clavier jusqu’à l’histogramme final. En une minute (lecture accélérée ×2), la vidéo fait le tour complet d’un mini-workflow quantitatif — choisir ses actifs, pondérer un portefeuille, puis le projeter dans le futur — sans jamais ouvrir de notebook, de tableur ou de page web.

Démonstration complète : cote de Casablanca → construction d’un portefeuille → simulation Monte-Carlo de 10 000 trajectoires. Lecture accélérée ×2 ; les commandes et leurs sorties restent lisibles, et vous pouvez mettre sur pause pour lire le détail.

Ce que je fais réellement dans la vidéo

Le fil de la session tient en quatre commandes. Rien de plus.

1. bvc — la cote de Casablanca en direct

La première commande affiche l’état de la séance à la Bourse de Casablanca : les barres de capitalisation par secteur (Utilities, Retail Trade, Distribution Service…), le nombre de valeurs listées et leur répartition, puis la watchlist FIN_BVC mappée des noms .CA vers les tickers CSEMA de TradingView — Attijariwafa Bank, Maroc Telecom, BCP, Bank of Africa, Akdital, Sothema, Managem, Cosumar, Marsa Maroc… Le pied de table indique la source et la cadence de rafraîchissement : TradingView CSEMA scan + FX_IDC · refreshes every ~45s.

C’est le point de départ : on lit le marché, on repère une valeur, et on décide quoi mettre dans le portefeuille. Aucun onglet navigateur, aucune plateforme à ouvrir.

2. portfolio list — les portefeuilles existants

Ensuite, portfolio list liste les paniers déjà enregistrés dans ~/.fin/portfolios/ :

── portfolios ── /home/yirviel/.fin/portfolios
NAME               ASSETS    WEIGHT
FridayNight        3         105%
YirPort            0         0%
Yirviel            3         100%

Un portefeuille n’est qu’un petit fichier texte SYMBOLE<TAB>POIDS. YirPort part de zéro : c’est celui qu’on va construire dans la vidéo.

3. portfolio add — construire le panier en trois commandes

On ajoute les lignes une à une, chaque commande confirmant le poids retenu :

portfolio add YirPort AKT 30   →  AKT @ 30% added to YirPort
portfolio add YirPort ATW 50   →  ATW @ 50% added to YirPort
portfolio add YirPort STM 20   →  STM @ 20% added to YirPort

La composition retenue pour YirPort mélange deux valeurs de la BVC et une valeur internationale :

• ATW — Attijariwafa Bank (50 %) : le socle bancaire marocain, la position de stabilité.
• AKT — Akdital (30 %) : la valeur de croissance dans la santé privée, plus volatile.
• STM — STMicroelectronics (20 %) : un semi-conducteur coté à New York, pour la diversification hors Maroc.

On notera que le moteur sait aussi lire des portefeuilles dont les poids ne totalisent pas 100 % (FridayNight est à 105 %) : les poids sont simplement relatifs les uns aux autres.

4. mc — 10 000 trajectoires Monte-Carlo

La commande finale est la raison d’être du projet :

mc YirPort --years 2 --sims 10000 --initial 10000

Elle récupère l’historique quotidien de chaque titre, estime rendement et volatilité annualisés, puis tire 10 000 trajectoires sur deux ans :

Le terminal affiche alors, en un seul écran :

• l’allocation et les paramètres estimés — le rendement annualisé et la volatilité de chaque actif, puis ceux du portefeuille agrégé ;
• la valeur terminale — moyenne, médiane et percentiles (5ᵉ, 25ᵉ, 75ᵉ, 95ᵉ) à l’issue des deux ans ;
• le risque — probabilité de perte, VaR 95 %, CVaR 95 % et CAGR médian ;
• la distribution complète — un histogramme des 10 000 valeurs finales ;
• la graine — de quoi rejouer exactement la même simulation.

Les résultats chiffrés de la session

Allocation et paramètres estimés (historique du 14/12/2022 au 09/10/2026, 993 jours de cotation) :

On voit bien la mécanique de la diversification à l’œuvre : STM est de loin l’actif le plus volatil (49,4 %) et le plus risqué à détenir seul, mais une fois pondéré à 20 % dans un panier dominé par la banque, la volatilité du portefeuille retombe à 17,8 % — en dessous de celle d’ATW lui-même. C’est exactement l’effet recherché : la corrélation entre les actifs absorbe une partie du risque individuel.

Valeur terminale du portefeuille (départ 10 000 $, horizon 2 ans, 10 000 trajectoires) :

Distribution des 10 000 valeurs terminales : de 8 057 $ en bas de l’éventail à 30 315 $ en haut.

Comment lire ces chiffres. La VaR à 95 % répond à la question « dans le pire des cas raisonnable, où en est-on ? » : ici, il y a 95 % de chances statistiques que le portefeuille termine au-dessus de 3,2 % de gain. Le CVaR à 95 % (ou perte moyenne conditionnelle) va plus loin : c’est la perte moyenne dans les 5 % de scénarios les plus défavorables, soit −7,3 %. Autrement dit, même dans sa queue de distribution la plus mauvaise, cette exécution ne prédit pas de destruction du capital — mais c’est une propriété de l’échantillon et de l’historique utilisé, pas une garantie. La probabilité de perte de 0,0 % signifie qu’aucune des 10 000 trajectoires ne finit sous les 10 000 $ de départ : un résultat séduisant, mais qu’il faut immédiatement tempérer par les limites du modèle (voir plus bas).

Simuler votre propre portefeuille

Le modèle interactif reprend le moteur Python de FIN : mêmes rendements journaliers alignés, même bootstrap par blocs de cinq jours, même annualisation à 252 périodes. Le run de référence est la simulation publiée, avec sa graine ; dès qu’un paramètre change, le calcul est refait dans le navigateur, dans un Web Worker, avec une graine reproductible.

Voir aussi. Le Risk Dashboard applique une lecture historique complémentaire — VaR/CVaR, drawdown, Sharpe, Sortino, volatilité glissante et scénarios de stress — à un portefeuille pondéré de valeurs BVC et d’ETF globaux.

Note de reproduction. Le run de référence (graine 2 086 474 496) reproduit la moyenne, la médiane, les percentiles, la VaR/CVaR et le CAGR publiés. La probabilité de perte calculée est 3,95 %, et non 0,0 % : 395 trajectoires sur 10 000 terminent sous 10 000 $. C’est cohérent avec le 5ᵉ percentile à 10 322 $ et le bas de l’histogramme à 8 057 $, qui est le quantile à 0,5 %, pas le minimum absolu. Le détail est dans la section Methodology du simulateur.

Sous le capot : comment ça marche

Le moteur est un script Python (~/.fin/mc.py) appelé par le toolkit bash. Sa logique :

1. Lecture du portefeuille — le fichier SYMBOLE<TAB>POIDS de ~/.fin/portfolios/.
2. Récupération de l’historique — d’abord un éventuel cache local, puis le websocket TradingView (qui couvre la BVC, les actions US, la crypto et le FX), avec Yahoo Finance en repli ; un CSV local est aussi accepté en mode hors-ligne.
3. Bootstrap par blocs — plutôt que de tirer chaque rendement journalier isolément, le moteur rééchantillonne des blocs de 5 jours de rendements conjoints. Cette astuce préserve une partie de l’autocorrélation et des régimes de marché, là où un tirage purement i.i.d. lisserait trop la série.
4. Agrégation — les rendements jour par jour sont recombinés selon les poids, sur 252 jours de bourse par an, et répétés sur l’horizon demandé.
5. Statistiques — percentiles, VaR, CVaR, CAGR, histogramme ; une graine est tirée et affichée pour rendre l’exécution reproductible.

C’est la même famille de méthode que celle documentée dans le Casablanca Quant Framework (simulation Monte-Carlo + VaR 95 % sur une allocation BVC), à une différence près d’échelle : là où l’ancien projet demandait un notebook Jupyter, un Makefile et un coffre chiffré, ici tout tient dans une commande du prompt, sur n’importe quel portefeuille.

Comment j’en suis arrivé là

L’enchaînement n’a rien d’accidentel — c’est la même idée qui revient, débarrassée à chaque étape de sa lourdeur.

Tout commence par le Casablanca Quant Framework, un travail académique mené à l’ENCG Casablanca : analyser fondamentalement deux valeurs de la BVC, Akdital et Attijariwafa Bank, puis simuler une allocation de 1 000 000 MAD sur mille trajectoires afin d’en tirer une Value at Risk. Ce projet m’a appris la méthode — mais il vivait dans un notebook, avec un pipeline de nettoyage et un stockage chiffré. Le refaire pour un nouveau portefeuille voulait dire rouvrir tout l’atelier.

Vient ensuite FIN, un terminal bash qui met le marché dans le prompt : cotations en direct, crypto, devises, et surtout un module Casablanca natif — parce que Yahoo a abandonné le MASI en 2019 et que la cote marocaine manquait à presque tous les outils gratuits. FIN a résolu la couche données : lire la BVC en temps réel devient trivial.

La vidéo de cette page est le point où les deux se rejoignent : j’ai greffé le moteur Monte-Carlo du framework quantitatif directement dans FIN, sous la forme de deux commandes — portfolio pour bâtir le panier, mc pour le simuler. La méthode statistique est la même, mais elle est passée d’un atelier de recherche à un geste de terminal. C’est cette continuité qui m’intéresse dans ce projet : montrer qu’un outil de recherche quantitatif n’a pas besoin d’être une usine — la partie qui compte (bootstrap, agrégation, VaR) tient en quelques centaines de lignes et s’appelle avec trois arguments.

Pourquoi c’est utile

• Pour un étudiant en finance de marché : passer de la théorie (« qu’est-ce qu’une VaR ? ») à la pratique (« quelle est la VaR de mon portefeuille BVC ? ») en une commande, pendant un cours, sans installation lourde.
• Pour la cote de Casablanca : la BVC est mal desservie par les outils gratuits. La rendre interrogeable depuis un terminal, avec sa propre simulation de risque, remet un marché entier à portée de main.
• Pour un analyste : le même moteur s’applique à des univers mixtes — ici deux valeurs marocaines et un semi-conducteur américain — ce qui permet de tester rapidement une hypothèse d’allocation avant de sortir un vrai modèle.
• Comme brique open source : le code est public, les données proviennent de sources gratuites, et le dépôt accepte les contributions.

Stack technique

Limites

• Le modèle suppose la « normalité » et une volatilité future égale à l’historique. C’est la simplification classique de tout Monte-Carlo paramétrique : elle sous-estime généralement les événements extrêmes, dont les queues de distribution sont plus épaisses dans la réalité.
• Les corrélations sont capturées par blocs, pas par une matrice explicite. Le bootstrap conjoint préserve une partie de la dépendance entre actifs, mais ce n’est pas un modèle de covariance complet — la diversification réelle peut être surestimée.
• La source de données n’est pas un flux agréé. La cote vient du scan CSEMA de TradingView : excellente pour de la veille, pas pour un usage réglementaire.
• Pas de coûts de transaction, pas de fiscalité, pas de liquidité. La simulation porte sur des rendements purs ; elle ignore les frais, les spreads et l’impact de marché.
• Une graine, un résultat. Le chiffre exact change d’une exécution à l’autre si la graine change ; la graine affichée sert justement à figer une exécution pour la comparer.
• Ce n’est pas un conseil en investissement. C’est un outil de visualisation et de pédagogie du risque — vérifiez avant de vous fier à un chiffre.

Reproductibilité

Le code complet de FIN — moteur bash, commandes bvc / portfolio / mc, installeur idempotent — est open source :

Deux projets liés complètent cette page, si vous voulez remonter le fil :

Conclusion

Cette vidéo d’une minute résume une conviction : entre le notebook de recherche et l’outil du quotidien, il n’y a qu’une question de friction. La méthode de Monte-Carlo et de Value at Risk n’a pas changé depuis le Casablanca Quant Framework — c’est la même idée née d’un devoir d’école. Ce qui a changé, c’est qu’elle s’appelle maintenant en trois arguments depuis le prompt, sur les données live de la Bourse de Casablanca. La prochaine étape naturelle : modéliser explicitement la matrice de corrélation entre actifs (plutôt que des blocs conjoints) et exposer la VaR comme entrée d’un optimiseur de frontière efficiente, pour passer d’un portefeuille choisi a priori à une allocation qui maximise le rendement sous contrainte de risque.

Academic origin

This project grew out of an ENCG Casablanca exercise: manage a simulated 1,000,000 MAD portfolio on the Casablanca Stock Exchange, justify the positions, and answer the risk question rather than pretend to forecast the future. The first solo rebuild paired a fundamental thesis on Akdital and Attijariwafa Bank with a 1,000-path Monte Carlo and a 95% VaR. That work is preserved as a PDF: the original academic report.

The current page is the production version of the same idea — a reusable terminal workflow, 10,000 paths, block-bootstrapped joint returns, VaR/CVaR, and a replayable seed. The two-stock fundamental analysis now lives where it belongs: the Akdital DCF and the ATW equity note in the academic equity-pitch exercises.