formulation/docs/help/ingredients/units-and-equivalencies.md

Units of Measure & Custom Equivalencies

Formulation maintains a rigorous, multi-dimensional unit conversion engine that enforces physical dimensional rules while supporting culinary volume-to-weight equivalencies.

---

1. Dimensional Systems

Every unit belongs to a fundamental physical dimension:

• Mass (Base unit: gram): gram, kilogram, pound, ounce_mass.
• Volume (Base unit: milliliter): milliliter, liter, cup_us (240 mL legal), tablespoon_us, teaspoon_us, fluid_ounce_us.
• Count (Base unit: each): each, clove, head, bunch.
• Temperature (Affine scale): fahrenheit, celsius.

---

2. Density & Ingredient-Specific UoM Equivalencies

Because ingredients possess different bulk densities (e.g. 1 cup of all-purpose flour = ~120g, whereas 1 cup of honey = ~340g), volume-to-mass conversions require density records.

A. UoM Equivalencies Panel

• On each ingredient page, the UoM Equivalency tab allows defining custom portion measurements:
  • Example: 1 cup = 125 g
  • Example: 1 medium apple = 182 g
  • Example: 1 clove garlic = 3 g

B. Resolution Precedence

1. Reviewed Portions / Measures: Checked first for an exact unit match (e.g. cup or each).
2. Bulk Density Measurements: Checked if converting between standard volume and mass dimensions.
3. Canonical Unit Factor: Applied for within-dimension conversions (e.g. lb to oz).