Analyse approfondie : standardisation des masses & rendement

Gram est profondément ancré dans la réalité physique. Contrairement aux parseurs Markdown basiques qui se contentent de formater du texte, @gram-lang/analyzer comprend qu’une “tasse de farine” et une “tasse d’eau” ont des poids radicalement différents.

Cette page explique le moteur physique derrière les calculs de masse et de rendement de Gram.

Les trois piliers de la physique

Gram modélise les propriétés physiques des ingrédients selon trois concepts distincts au sein de votre base de données. Cette séparation stricte garantit l’exactitude des calculs, que vous exprimiez vos quantités en volumes, en unités ou en poids.

1. Densité (density) : Utilisée strictement pour convertir les Volumes en Masse.
   • Exemple : 1 tasse de lait -> 240 g (en utilisant une densité de 1,03 g/ml).
2. Poids Unitaire (unit_weight) : Utilisé strictement pour convertir les Nombres en Masse.
   • Exemple : 1 avocat -> 150 g (le poids moyen d’un avocat entier).
3. Rendement (yield) : Le Facteur de Déchet. Il sert strictement à calculer le ratio entre la Masse Nette comestible et la Masse Brute à l’achat (en déduisant épluchures, noyaux, os, etc.).
   • Exemple : Un avocat a un rendement de 0.70 (30 % correspond au noyau et à la peau).

Le but de la standardisation des masses

Le but principal de l’Analyseur est de calculer la Masse Totale d’une recette. C’est essentiel pour l’estimation nutritionnelle, le calcul du coût, et les ratios de pâtisserie.

Pour ce faire, l’Analyseur doit convertir chaque quantité d’ingrédient en une base de référence unifiée : les grammes (g).

L’algorithme de conversion

Lorsque l’Analyseur rencontre un ingrédient, il le passe par un algorithme de priorité stricte pour trouver sa masse :

1. Masse Précise : Si vous avez écrit @farine{200 g} ou @boeuf{1 kg}, l’Analyseur n’a rien à faire. Il convertit simplement cela en grammes.
2. Surcharge Utilisateur : Si vous avez fourni une surcharge de densité spécifique dans le frontmatter YAML de la recette (ex : densities: { farine: 0.55 }), il utilise cette valeur explicite pour convertir le volume demandé en masse.
3. Densité de la Base de Données : Si vous avez demandé un volume connu (ml, tasse, c.à.s, c.à.c) et que votre ingredients.yaml contient un champ density pour cet ingrédient, il calcule Volume * Densité = Masse.
4. Poids Unitaire de la Base de Données : Si vous avez demandé un nombre (@oeuf{3} ou @ail{2 gousses}) et que votre base de données contient un champ unit_weight, il calcule Nombre * Poids Unitaire = Masse.
5. Incomplet : Lorsqu’un volume n’a aucune densité disponible (ni surcharge, ni entrée en BDD) ou qu’un nombre n’a pas de unit_weight, l’Analyseur refuse d’effectuer une estimation arbitraire. Il ne supposera pas une densité par défaut (comme traiter tout liquide comme de l’eau), ce qui fausserait silencieusement la liste de courses. Le calcul échoue, l’ingrédient est marqué comme incomplet, et il reste listé dans son unité brute non convertie.

Calcul du rendement (le facteur de déchet)

Dans les cuisines professionnelles, il y a une différence fondamentale entre ce qui va dans la casserole et ce que vous achetez au magasin.

• Masse Nette (Portion Comestible) : Le poids de l’ingrédient après épluchage, évidage ou parage.
• Masse Brute (Poids d’Achat) : Le poids de l’ingrédient tel qu’il est acheté.

Le rapport entre ces deux éléments est le Facteur de Rendement.

Comment Gram gère le rendement

Par défaut, Gram part du principe que tout ingrédient mentionné dans une recette correspond à sa Masse Nette. Le générateur de liste de courses remonte ensuite la chaîne à l’envers : il utilise le rendement (yield) et le poids unitaire (unit_weight) pour déterminer la quantité exacte à acheter.

Regardons deux scénarios pour un avocat (unit_weight: 150g, yield: 0.70) :

Scénario A : Écrire en Nombres (@avocat{1})

1. L’Analyseur lit “1 unité”.
2. Il applique le unit_weight : 1 * 150 g = 150 g. C’est la Masse Brute (l’avocat entier acheté) — stockée en tant que purchasingMass de l’ingrédient.
3. Il applique le yield (rendement) vers l’avant pour trouver ce qui entre réellement dans la recette : 150 g * 0.70 = 105 g. C’est la Masse Nette — la valeur utilisée pour la masse totale de la recette et les calculs de nutrition.

Scénario B : Écrire en Masse (@avocat{200 g})

1. L’Analyseur lit “200 g”. Il suppose qu’il s’agit de la Masse Nette dont vous avez besoin dans le bol.
2. Il applique le yield à l’envers pour trouver le poids de la liste de courses : 200 g / 0.70 = 285 g. C’est la Masse Brute.
3. Il peut utiliser le unit_weight pour vous dire combien en acheter : 285 g / 150 g = 1,9 avocats (donc, en acheter 2).

Cela garantit que vous ne vous retrouverez jamais à court d’ingrédients après les avoir préparés.