Mise à l'échelle dynamique des recettes

Gram est conçu pour s'assurer que les recettes se mettent à l'échelle mathématiquement de manière parfaite à travers tout son écosystème. Que vous utilisiez le Playground interactif, que vous génériez des documents HTML/Markdown, ou que vous exécutiez des commandes CLI, Gram prend en charge nativement deux fonctionnalités puissantes pour la cuisine basée sur des ratios (comme la pâtisserie ou la boulangerie) : les Quantités Relatives et le Pourcentage du Boulanger.

Ce guide vous montre comment utiliser les Quantités Relatives pour construire des recettes dynamiques et auto-documentées basées sur des ratios, et comment utiliser le Pourcentage du Boulanger (Baker's Math) pour afficher des recettes traditionnelles au format de pourcentage.

Les limites des quantités statiques

Imaginez une recette de pain :

[Mélanger] La @farine{500 g}, l'@eau{350 ml}, le @sel{10 g} et la @levure{5 g}.

Si vous mettez cette recette à l'échelle avec un facteur 2 (ex : via gram build --scale 2), tout est doublé. Et si vous n'avez plus que 400 g de farine, vous pouvez utiliser la mise à l'échelle par référence : gram build --scale farine=400g. Gram calculera le multiplicateur (0.8) et ajustera tout automatiquement.

Alors, pourquoi aurions-nous besoin d'autre chose ?

Le problème survient lorsque vous voulez modifier la recette elle-même. Que se passe-t-il si vous voulez augmenter l'hydratation de 70 % à 75 % ? Vous devriez calculer manuellement ce que représentent 75 % de 500 g, et modifier 350 ml en 375 ml. La logique sous-jacente de la recette (les ratios) est cachée derrière des nombres statiques, ce qui la rend difficile à lire et difficile à ajuster.

La solution pour les recettes par ratios : Les Quantités Relatives

Certaines recettes sont fondamentalement construites autour de la relation mathématique entre les ingrédients, plutôt que sur des quantités absolues strictes (ex: une pâte à pain définie par ses 70 % d'hydratation).

Dans Gram, vous pouvez exprimer ces relations directement dans le code source en utilisant des Quantités Relatives (% @&cible pour les ingrédients, ou % &cible pour les variables intermédiaires). Cela permet à la recette de se recalculer dynamiquement lorsque vous modifiez un seul pourcentage.

1. Définir l'Ancre (La Cible)

Commencez par définir la farine comme un ingrédient standard dans votre recette.

[Ajouter] La @farine{500 g}.

2. Définir les Relatifs

Maintenant, remplacez les quantités statiques de l'eau, du sel et de la levure par des pourcentages pointant vers la farine. Puisque la farine a déjà été définie dans une étape précédente, vous la référencez en utilisant @&farine.

[Ajouter] La @farine{500 g}.

[Verser] L'@eau{70% @&farine}, le @sel{2% @&farine}, et la @levure{1% @&farine}.

Astuce : Vous pouvez aussi définir une variable intermédiaire (ex: un mélange) avec ->&pâte et calculer ensuite une quantité relative par rapport à elle en utilisant &pâte (ex: @sel{2% &pâte}). La syntaxe suit tout naturellement la façon dont vous référencez habituellement les éléments dans Gram !

Mettre à l'échelle la recette dynamique

Parce que les relations sont encodées directement dans la recette, Gram gère les mathématiques dynamiquement. Tout boulanger qui lit votre fichier .gram voit immédiatement qu'il s'agit d'une pâte hydratée à 70 %.

Si vous voulez ajuster la recette pour une pâte plus humide à 75 % d'hydratation, vous ne changez qu'un seul nombre :

[Verser] L'@eau{75% @&farine}

Gram se charge des calculs. Vous n'aurez plus jamais à calculer manuellement des poids absolus lors de la conception ou de l'ajustement de vos recettes.

Mise à l'échelle universelle

Vous pouvez mettre à l'échelle les recettes visuellement dans le Playground, ou depuis le CLI en utilisant le paramètre --scale (disponible sur view, build, print, et export) :

gram view pain.gram --scale farine=400g

Gram calculera le facteur global (400/500 = 0.8), mettra l'ancre (farine) à l'échelle (400 g), et les ingrédients relatifs s'évalueront parfaitement sur cette nouvelle base (Eau : 70 % de 400 g = 280 g).

Les limites de la mise à l'échelle par référence

Puisque la mise à l'échelle par référence dérive le facteur à partir de la quantité d'un ingrédient, tous les ingrédients ne peuvent pas servir de cible — seul un ingrédient avec une quantité absolue propre et authentique se qualifie. Si vous tentez de passer l'un des éléments suivants, Gram le rejettera avec une erreur spécifique plutôt que de calculer silencieusement un facteur erroné :

Vous avez tenté d'utiliser...	Pourquoi c'est rejeté	Que faire à la place
Une quantité relative (ex : eau, définie comme 70% @&farine)	Sa valeur est dérivée d'un autre ingrédient — elle ne peut pas non plus servir de référence	Mettez à l'échelle l'ingrédient ancre (--scale farine=400g)
Un ingrédient fixe (@=) ou une quantité textuelle comme une pincée	Il ne se met jamais à l'échelle par définition, il ne peut donc pas non plus décrire un facteur d'échelle	Choisissez un autre ingrédient qui évolue effectivement avec la recette
Un ingrédient utilisé uniquement à l'intérieur d'une sous-recette (ex : zeste-de-citron, partie d'un composite <@citron)	Il n'est pas directement déclaré avec sa propre quantité — seul le parent composite en possède une	Mettez à l'échelle le parent composite (ex : --scale citron=4) — son propre total est une cible valide
Une option au sein d'un groupe d'ingrédients alternatifs (@beurre{100 g}|@margarine{100 g})	Choisir une option de manière isolée ne représente pas le choix "soit l'un soit l'autre" qu'exprime la recette	Mettez à l'échelle un ingrédient différent et non ambigu, ailleurs dans la recette
Un ingrédient fragmenté sur deux unités incompatibles dans la recette (ex : 300 g dans une étape, 2 tasses dans une autre)	Le total de la liste de courses ne peut pas être réduit à un seul chiffre par lequel diviser	Réécrivez la recette en utilisant une seule unité pour cet ingrédient, ou mettez à l'échelle par rapport à un autre ingrédient
Une unité appartenant à une famille physique différente (ex : eau=1L contre une recette écrite en g) sans aucune densité disponible	Convertir de la masse au volume requiert une densité spécifique à l'ingrédient	Ajoutez une densité via gram db enrich, ou déclarez-en une directement dans le bloc densities: du frontmatter de la recette

Les unités d'une même famille se convertissent automatiquement — --scale farine=1kg pour une recette écrite en 500 g fonctionne directement (facteur 2), sans recourir à la base de données. Croiser les familles (masse ↔ volume) fonctionne également, tant qu'une densité est disponible : soit via votre ingredients.yaml (gram db enrich), soit via une surcharge ponctuelle au sein de la recette elle-même :

---
densities: ["eau:1.0"]
---

Avec cela, --scale eau=150g sur une recette écrite en ml se résout correctement — pas besoin de base de données pour cet ingrédient précis.

Pourcentage du Boulanger (Baker's Math)

Si les Quantités Relatives sont parfaites pour concevoir des recettes dynamiques, les professionnels utilisent souvent un concept appelé Pourcentage du Boulanger pour lire et analyser des recettes statiques. Avec le Pourcentage du Boulanger, l'ingrédient principal (généralement la farine) est défini comme valant 100 %, et tout le reste est affiché en pourcentage de ce poids.

Si vous avez une recette classique avec des poids absolus, vous pouvez utiliser le Modificateur de Pourcentage du Boulanger (*) pour indiquer explicitement à Gram : "Cet ingrédient est le point de référence de 100 %".

[Ajouter] La @*farine{500 g}, l'@eau{350 g} et le @sel{10 g}.

La recette compilée calculera automatiquement ces pourcentages afin que n'importe quelle interface (frontend) puisse les afficher.

Lorsque vous utilisez le CLI, vous pouvez afficher ces pourcentages en ajoutant l'argument --bakers-math :

gram view pain.gram --bakers-math

La sortie affichera automatiquement le pourcentage de chaque ingrédient par rapport à la farine :

  farine                 100% (500 g)
  eau                    70% (350 g)
  sel                    2% (10 g)

Si votre recette n'inclut pas le modificateur @*, vous pouvez tout de même forcer le calcul des pourcentages du boulanger en spécifiant explicitement l'ingrédient de référence à la volée :

gram view pain.gram --bakers-reference=farine

(Vous pouvez également utiliser l'argument --bakers-math-only si vous souhaitez masquer complètement les poids absolus.)

Ingrédients Fixes

Parfois, une recette contient des ingrédients qui ne doivent jamais être mis à l'échelle, peu importe le nombre de portions que vous réalisez. Par exemple, l'huile de friture dans une poêle, ou une pincée de sel.

Vous pouvez utiliser le Modificateur Fixe (=) pour protéger un ingrédient de la mise à l'échelle :

Faire chauffer @=huile de friture{1 L} dans une sauteuse.

Si vous exécutez gram build --scale 2, l'huile de friture restera à 1 L.

Résumé

En combinant les Quantités Relatives pour les ratios et les Quantités Fixes pour les constantes immuables, vous pouvez écrire des recettes qui s'adaptent parfaitement à n'importe quelle contrainte de votre garde-manger ou taille de portion.