@woosh/meep-engine 3.55.0 → 3.57.0

package/src/generation/foliage/SHOOT_SYSTEMS_ALL_SPECIES_BRIEF_2026_10_26.md

@@ -0,0 +1,248 @@
+# Shoot Systems for Every Woody Species
+
+Follows `ANNUAL_SHOOTS_BRIEF_2026_10_25.md`, which grew the oak's twigs year by year and put its leaves on them.
+
+## Problem
+
+Only the oak grows a twig layer. The other woody presets still hang their leaves on cards of 0.7-1.3 m, drawn by the
+density rule along their framework branches. The oak's model cannot simply be copied: it hard-codes four oak facts.
+
+| What the oak model assumes | Where | Species where it is false |
+| :--- | :--- | :--- |
+| Leaves live one season, on the current unit only | `foliage_collect_attachments`, joint mechanics | pine (needles kept 3-4 years), spruce (7-9) |
+| Leaves crowd at the unit's tip: one card a unit | `MEDIAN_CURRENT_SHOOT_LENGTH`, the `rosette` arrangement | willow and birch long shoots (leaves along the shoot), conifers (needles along it) |
+| Every bud that grows out makes an axis that extends every year | `shoot_demography_grow` | maple and birch: most buds become short shoots, which grow millimetres a year and leaf every year |
+| Oak's bud zones, length distributions and wood diameter | `SUBAPICAL_U_*`, `MEDIAN_U_*`, `NEGATIVE_BINOMIAL_P`, `shoot_radius` | every other species |
+
+**Baseline**, seed 1337, master `ee5c666c3`, crown fullness from a raster fitted to the leaves (the side opacity is over
+pixels within 10 cm of a leaf):
+
+| preset | cards | median card | leaf area | side opacity | LAI over top silhouette |
+| :--- | ---: | ---: | ---: | ---: | ---: |
+| oak | 2,261 | 0.17 m | 93 m^2 | 0.49 | 3.2 |
+| pine | 693 | 0.76 m | 174 m^2 | 0.69 | 5.5 |
+| birch | 399 | 0.72 m | 45 m^2 | 0.44 | 3.2 |
+| willow | 1,455 | 1.27 m | 241 m^2 | 0.67 | 4.5 |
+| maple | 478 | 0.88 m | 150 m^2 | 0.66 | 3.9 |
+| spruce | 1,191 | 0.69 m | 161 m^2 | 0.57 | 4.7 |
+| shrub | 114 | 0.56 m | 10 m^2 | 0.48 | 1.5 |
+
+## Scope
+
+- **Woody presets get shoot systems:** oak, pine, birch, willow, maple, spruce, shrub.
+- **Palm and fern do not.** A palm grows from one apical meristem and never branches. A fern's fronds rise from its
+  rhizome. Neither has a twig system, and their frond cards already draw single leaves at real size (palm 1.85 m,
+  fern 0.95 m).
+- **Species each preset stands for.** These are needed to pick sources.
+  - **oak:** *Quercus robur / petraea* (unchanged).
+  - **pine:** *Pinus sylvestris*, as its comments already say.
+  - **spruce:** *Picea abies*.
+  - **birch:** *Betula pendula* (white bark, pendulous twigs).
+  - **maple:** *Acer rubrum*. Its anthocyanin potential of 0.9 is a red-autumn maple, and red maple has the best data.
+  - **willow:** a weeping willow (*Salix babylonica*, *S. x sepulcralis*), with pendulous-willow and *S. alba* data.
+  - **shrub:** *Corylus avellana* (hazel), which matches its multi-stemmed habit and ovate leaves. The preset names no
+    genus today; this is my pick.
+
+## Sources
+
+Read in the paper itself unless marked. "2nd" is second-hand (abstract or citing paper), and "summary" was read
+through a web summarizer and must be checked before it goes into code.
+
+**Red maple.** [W1966] Wilson, B.F. (1966). Development of the shoot system of *Acer rubrum* L. Harvard Forest Paper
+14. 38 felled trees up to about 115 years old. [C1971] Critchfield, W.B. (1971). Shoot growth and heterophylly in
+*Acer*. J. Arnold Arboretum 52(2): 240-266. [G1980] Gregory, R.A. (1980). Can. J. For. Res. 10: 316-326 (sugar maple).
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Long vs short shoot | long elongates > 2 cm a year and bears laterals; short < 2 cm, none; either can become the other | W1966 p. 2 |
+| Short shoots, share of all shoots | 85-95% | W1966 abstract, p. 10 |
+| New laterals a long shoot yields a year | order 2 on the stem: 1.8 long + 4 short; 3rd/2nd: 1.5 + 4; 4th/3rd: 0.1 + 4; 5th/4th: 0.03 + 4 | W1966 p. 10, Table 2 |
+| Bud fates along a 1-year shoot | top pairs long, middle pairs short, lowest pair may abort | W1966 p. 3, Fig. 1 |
+| Annual length increment by order 2-6 | 8.8, 4.5, 3.6, 3.4, 2.7 cm | W1966 p. 6 |
+| Leaf nodes on last season's shoot | long 7.8 (4-11), short 2.0 (1-3) | C1971 Table 1 |
+| Leaves per shoot by order | long 16, 14, 12, 8, 6 (orders 1-5); short 6 (orders 2-5), 4, 2 | W1966 Table 4 |
+| Area per leaf | long shoot 14-64 cm^2; short shoot 10-44 cm^2 | W1966 Table 4 |
+| Leaf area from length | log A = 0.0898 + 1.81 log L | W1966 p. 6 |
+| Petiole | 0.6-1.14 of the blade (early leaves), 0.3-0.8 (late) | C1971 p. 256 |
+| Survival | 1-6 (mean 2) live 2nd-order long shoots per annual group; shaded branches die | W1966 Fig. 7, p. 19 |
+
+**Silver birch.**
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Short shoot | one bud; two or three leaves a year; grows a couple of millimetres a year; carries most of the foliage; can become a long shoot | Jones & Harper 1987, Proc. R. Soc. B 232: 19-33 (2nd); Kull et al. 2003, Ann. Bot. 91: 559-569, pp. 560-561; Lintunen 2013, Diss. For. 165, p. 27 |
+| Short shoots | never sylleptic; in the upper crown at the base of last year's shoot | Kull et al. 2003 p. 567 |
+| Long shoot | many buds on elongated internodes; long-shoot lengths 0-120 cm, order means 0-30 cm (figure only) | Jones & Harper 1987 (2nd); Lintunen 2013 Fig. 7 |
+| Short shoots per branch | 46-54 | Lintunen 2013 Table 3 |
+| Leaf blade | 3-7 x 2.5-5 cm | Flora of North America vol. 3 |
+
+**Willow.**
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Bud fates, pendulous willow ('Prairie Cascade', young trees) | 40% sylleptic, 29% proleptic shoots | Remphrey & Pearn 2006, Can. J. Bot. 84: 1531-1541 (2nd, abstract) |
+| Shedding, same | 7% of shoots in year 1, more than half by year 3, survivors on the parent's upper half | same |
+| *S. alba* annual shoots | 5-25 cm, at 30-60 degrees; no sylleptic shoots; no short shoots | Héja 2007, Tilia 13: 77-94, p. 82 |
+| Cladoptosis | shoots shed in autumn through an abscission zone, mostly 1-2 years old | Héja 2007 pp. 79-80 |
+| Leaf blade | *S. babylonica* 9-16 x 0.5-2 cm; *S. x sepulcralis* 7-14 x 0.9-1.8 cm | Flora of North America vol. 7; JANAS 29(1) |
+
+**Scots pine.**
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Net shoots per last year's shoot on a branch (Rb) | 1.35-1.42 in low light, rising with light and with shoot length; constant over a branch's life | Niinemets & Lukjanova 2003, Ann. For. Sci. 60: 195-208, pp. 198-200 |
+| Needle sets kept | 3.7 (S. Finland), 2.8 (Estonia); median shed at 4 years, 15% reach 5 | Pensa & Jalkanen 1999, Silva Fennica 33: 171-177, pp. 173-175 |
+| Needle length | 52 mm (fertile site), 25 mm (bog); unchanged with age | Niinemets & Lukjanova 2003 Table I |
+| Fascicles per cm (leaders) | 7.8 (6.9-8.5 stand means) | Salminen & Jalkanen 2006, Silva Fennica 40: 183-194, Table 3 |
+| Branching | stops at relative light 0.20-0.25; negligible below 0.6 of tree height | Ilonen et al. 1979, Silva Fennica 13, pp. 319-321 |
+
+**Norway spruce.**
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Bud fates on 1-year shoots, healthy trees | about 64% flush, 30% dormant but viable, 6% abort | Polák et al. 2006, For. Ecol. Manage. 225: 337-348, p. 344 |
+| Needle retention | 7-9 years; 50% of a cohort shed by 5.5 years, all by 12 | Polák et al. 2006 p. 342; Muukkonen & Lehtonen 2004 (2nd) |
+| New shoot, needles | mean 4.8 cm (2.2-11.3); 18-31 needles per cm | Bellan et al. 2019, Austrian J. For. Sci. 136: 1-26 |
+| Whorl zone | whorl branches in the top 20% of a unit; internodal branches short-lived | Colin & Houllier 1992, Ann. Sci. For. 49: 511-538 |
+| Shoot to mother angle | 60% between 40 and 70 degrees | Fabrika et al. 2019, BioResources 14: 908-921, Table 7 |
+
+**Hazel.** Grisafi et al. 2024, in silico Plants 6(1) diae004 (open access; read through a summarizer, to verify):
+1.13 buds a node; vegetative bud burst 0.97 distal to 0.62 proximal; shoot from a vegetative bud mean 4.1 cm; 8 nodes
+on 10-25 cm shoots; the apical bud dies (sympodial). An orchard cultivar. Leaf area 41 cm^2 in sun (Catoni et al.
+2015, Photosynthetica 53: 35-46, Table 2).
+
+## Sources supplied 2026-10-26
+
+Alex supplied the paywalled papers. Each was read in full except where a figure is "read approximately".
+
+**[M1982]** Maillette, L. (1982). Structural dynamics of silver birch. I. The fates of buds; II. A matrix model of the
+bud population. *J. Appl. Ecol.* 19: 203-218, 219-238. Three mature open-grown trees, 4-10 m, North Wales; about
+13,000 buds.
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Buds per long shoot | mode 4, on its late leaves only | I p. 213, Fig. 9 |
+| Leaves per long shoot | mode 6 | I p. 213 |
+| Long-shoot length | modal class 51-100 mm | I p. 210, Fig. 6a |
+| Long-shoot apex | always aborts; growth is sympodial | I p. 206 |
+| Short shoot | < 3 mm a year; two or three leaves; one bud; "a large proportion died"; few become long | I pp. 205-213 |
+| Leaves on short vs long shoots | B1 12,000 / 10,000; B2 5,300 / 3,100; B3 3,000 / 1,300 (figure) | I Fig. 2 |
+| Bud population growth a year (lambda) | whole crown 1.38; top 1.52; bottom 0.999 | II Table 1 |
+
+**[JH1987]** Jones, M. & Harper, J.L. (1987). The influence of neighbours on the growth of trees. II. The fate of buds
+on long and short shoots in *Betula pendula*. *Proc. R. Soc. Lond. B* 232: 19-33. Four-year-old trees in open
+grassland; values for the low-interference zone.
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Long-shoot buds becoming long shoots | about 50% on the youngest branches; 16-26% on older ones | pp. 21-22, Fig. 2 |
+| Buds surviving a year | 62% (year 2), 57% (year 3) | p. 26 |
+| Leaves per long shoot | commonly 4-8; internodes 15-25 mm | pp. 19-20 |
+
+**[KK1991]** Kellomäki, S. & Kurttio, O. (1991). A model for the structural development of a Scots pine crown based on
+modular growth. *For. Ecol. Manage.* 43: 103-123. 25 trees, 7-19 years, eastern Finland. Order 0 is the stem.
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Daughter shoots (terminal included) of a shoot L cm long | k + c L; order 0: 3.99 + 0.022 L; 1: 0.992 + 0.161 L; 2: 0.544 + 0.149 L; 3: 0.861 + 0.041 L | Eq. 1, Table 3 |
+| Lateral length / parent length, by parent order 0-3 | 0.570, 0.458, 0.355, 0.475 | Table 4 |
+| Terminal length / parent length, orders 0-4 | 1.196, 0.995, 0.913, 0.938, 0.999 | Table 4 |
+| Branching angle, orders 1-4 | 83, 61, 59, 65 degrees | Fig. 2 |
+| Needles surviving, by age 1-4 | 1, 0.90, 0.69, 0.22; a shoot without needles dies | p. 113 |
+
+**[KS1995]** Kellomäki, S. & Strandman, H. (1995). *Ecol. Model.* 80: 237-250. Needle length 0.4 L for shoots under
+10 cm, 4 cm above (Eq. 17).
+
+**[L2011]** Lintunen, A., Sievänen, R., Kaitaniemi, P. & Perttunen, J. (2011). Models of 3D crown structure for Scots
+pine and silver birch grown in mixed forest. *Can. J. For. Res.* 41: 1779-1794. Birch long shoot in branches: 14.6 cm,
+6 leaves of 11.8 cm^2; short shoots modelled with 2 leaves (Table A2, B20).
+
+**[NL2003]** Niinemets, Ü. & Lukjanova, A. (2003). *New Phytol.* 158: 75-89.
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Rb, net shoots per last year's shoot | *P. abies* 0.65-2.19 (example branch 1.516); *P. sylvestris* 0.98-4.17 | Table 1, Fig. 2 |
+| Rb against light | rises steeply with light; below 1 in deep shade | Fig. 5b |
+| Needle survival, *P. abies*, ages 2-9 | about 0.93, 0.93, 0.80, 0.76, 0.70, 0.57, 0.55, 0.19 (figure) | Fig. 4 |
+| Current shoot, *P. abies* | 0.6-4.6 cm, longer in light (figure) | Fig. 6 |
+
+**[H2007]** Hein, S. et al. (2007). *For. Ecol. Manage.* 242: 155-164. Norway spruce: 6.03 branches a stem whorl
+(4,851 over 804 whorls). Stem whorls only.
+
+**[RP2006]** Remphrey, W.R. & Pearn, M.A. (2006). Crown architecture development in *Salix* 'Prairie Cascade', a
+pendulous willow. *Can. J. Bot.* 84: 1531-1541. Young trees from cuttings.
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Terminal bud | aborts each year: sympodial | p. 1532 |
+| First-year shoot | 1,104 mm, 42 nodes | p. 1533 |
+| Bud fates | sylleptic 40.1%, proleptic 29.3%, aborted 24.6%, dormant 6.0% | Table 1 |
+| Laterals still present | 93% in year 2, 58% in year 3, 46% in year 4; the lowest quarter of the parent sheds almost all | p. 1535, Table 2 |
+| Current shoots in summer | hang at -80 to -88 degrees | Fig. 7 |
+
+## Gaps that remain
+
+| Missing | Species | Treatment |
+| :--- | :--- | :--- |
+| Lateral buds per shoot, lengths by order | spruce | pine's [KK1991] counts and ratios, stated as borrowed |
+| Short-shoot annual survival | birch, maple | birch: [JH1987]'s bud survival (0.6); maple: fitted to [W1966]'s 85-95% short-shoot share |
+| Shoot diameter | all but oak | [BB2000] Table 7 for every species |
+| Needle length | spruce | not found; chosen |
+| Hazel numbers | shrub | [Grisafi 2024] read through a summarizer only; to verify |
+
+## Design
+
+The oak's model, generalised. Every number becomes a `ShootSystemRule` field; the oak's defaults stay, and the oak's
+output is bit-identical after the refactor (checked against a fingerprint of three seeds).
+
+1. **Per-order arrays.** Lengths, outgrowth and insertion angles differ by branching order in every source, so these
+   fields hold one value per order, the last repeating.
+2. **Unit length** is `intercept[order] + slope[order] x parent unit length`, drawn as the oak's (1 cm plus a negative
+   binomial or Poisson count of centimetres, capped per order). The oak has slope 0 and intercepts from [BB2000];
+   pine has intercept 0 and [KK1991]'s ratios. Maple uses [W1966]'s means by order.
+3. **Bud zones** (`ShootBudZone`): where on the unit (u range), how many buds (`buds + buds_per_metre x length`),
+   and per order the share growing a long shoot next year, a sylleptic shoot this year, or a short shoot. The
+   oak's two zones are its subapical and median buds.
+4. **Sylleptic shoots** (willow) grow out in the same season as their mother unit, so a fast shoot branches at once.
+5. **Short shoots** (birch, maple) are a bud fate: a single-segment branch that grows `short_shoot_growth` a year, has
+   no laterals, leafs every year, and survives a year at `short_shoot_survival`. A shed mother takes them with it.
+6. **Vigour is Rb**, the net shoots a shoot leaves a year: sourced for pine and spruce [NL2003], birch (lambda,
+   [M1982]) and maple ([W1966]'s net yields); chosen for oak and willow.
+7. **Leaf cohorts.** `leaf_survival[age]` is the share of a unit's leaves alive at each age: `[1]` for the deciduous
+   species, [KK1991] for pine, [NL2003] for spruce. The skeleton records where each recent unit of a branch starts,
+   replacing `branch_current_growth_t`.
+8. **Cards tile the leafy units.** Each card covers the stretch of shoot its tile draws (`card_length * stem_length`),
+   scaled within 0.6-1.6 so a whole number fits, thinned by the cohort's survival. The oak keeps about one card per
+   unit. Short shoots carry one card at their tip.
+9. **Cards at real size.** The card length follows from the species' leaf length and how long its arrangement draws a
+   leaf in a tile. The leaves a card draws follow from the leaves per metre of shoot.
+10. **Two tile kinds** where a species has short shoots: the atlas draws its sprays (long-shoot stretches) and its
+    rosettes (a short shoot's 2-4 leaves) as separate variant sets, so neither card carries the wrong leaf count.
+
+## Crown fullness (the next question)
+
+The best measured target found: the US Forest Inventory's crown ratings, 15,011 leaf-on trees seen from the side
+(Randolph 2006, USDA GTR SRS-94, Tables 1-4).
+- **Crown density.** Branches and foliage block a mean 45% of the crown's outline (oaks, maples, birches 46-51%).
+- **Foliage transparency.** Within the foliated parts, only about 15% of skylight comes through, so they are 80-85%
+  opaque.
+
+So a healthy crown is dense clumps that fill about half its outline. Our probe measures opacity within 10 cm of a leaf,
+which is nearer the clumps: the oak reads 0.49 there against about 0.85. This is measured after the propagation, as
+asked.
+
+## Plan
+
+1. Generalise `ShootSystemRule` and `shoot_demography_grow`: zones, per-order arrays, syllepsis, short shoots. The
+   oak's fingerprint is unchanged.
+2. The writer: short shoots, opposite phyllotaxis, per-order angles; the unit record.
+3. Foliage and mechanics: leaf cohorts, tiled cards, short-shoot cards, tile kinds.
+4. Presets: pine, spruce, birch, maple, willow, shrub, each with carriers, a twig generator, a sourced rule and
+   real-size cards.
+5. Specs per species against their sources, mutation-tested.
+6. Measure every preset and look at each in the playground.
+
+## Landed (2026-10-26, uncommitted)
+
+Every woody preset grows its twigs from `shoot_rules`, each with its own `ShootGrowthConfig`, and the crown fills by
+light. What landed, the specs restated and the measured crowns are in `CROWN_FILLING_BRIEF_2026_10_26.md`.