Release/v3.5.0

CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## v3.5.0 - 2026-04-18
+
+Chemical coupling and adaptive signal. alpha_coupling and beta_modulation added as searchable
+signal parameters. Three signal-only behavioral descriptors. Descriptor library 15→18.
+
+### alpha_coupling [-1, 1]
+
+New Params field. Reception-to-growth coupling: G *= (1 + alpha * reception).clamp(min=0).
+Applied globally (no ownership gating) -- species B grows into species A's territory when B's
+receptor_profile aligns with A's emission_vector. Positive = chemotaxis (predation pathway).
+Negative = chemorepulsion. Zero = no coupling (previous behavior).
+
+### beta_modulation [-1, 1]
+
+New Params field. Adaptive emission: rate_eff = clip(emission_rate * (1 + beta * mean(reception)), 0, 0.1).
+Reception computed before emission each step. Positive = quorum sensing (amplify when stimulated).
+Negative = feedback inhibition (suppress when stimulated). Zero = static emission rate.
+
+### Signal-only descriptors
+
+Three new Descriptor objects with signal_only=True registered in REGISTRY:
+- emission_activity: mean G_pos * emission_rate over trace tail, normalized to [0,1]
+- receptor_sensitivity: mean |dot(convolved_signal, receptor_profile)| over trace tail, [0,1]
+- signal_retention: final_mass / initial_mass clipped to [0,1]; 1.0 for non-signal traces
+
+Descriptor dataclass gains signal_only: bool = False field. loop.py validates at search startup:
+raises ValueError if any signal_only descriptor is active without signal_field=True.
+RolloutTrace gains signal_emission_history, signal_reception_history, signal_retention fields.
+rollout.py captures these per-step during signal rollouts.
+
+### Quality metric adjustment
+
+Signal run weights: stability 0.3→0.2, retention 0.2→0.3. Non-signal unchanged (0.6/0.4).
+
+---
+
+## v3.4.0 - 2026-04-18
+
+Signal physics corrections, multi-component quality metric, signal observables, signal GIF,
+viewer improvements across archive and ecosystem pages.
+
+### Signal physics
+
+emission_rate and decay_rates made per-creature searchable (were hardcoded constants).
+standard_preset 300→500 steps. signal_preset auto-selects 800 steps with --signal-field.
+CREATURE_MASS_FLOOR raised 0.1→0.2. Reception moved before emission in localized.py.
+
+### Multi-component quality metric
+
+q = 0.6·min(compact(T/2), compact(T)) + 0.4·stability  (non-signal)
+q = 0.5·min(compact(T/2), compact(T)) + 0.2·stability + 0.3·retention  (signal)
+midpoint_state captured in rollout loop and stored on RolloutTrace.
+stability = clip(1 - drift/0.2, 0, 1) -- continuous version of persistent filter.
+
+### Signal observables
+
+SimOutput captures signal_total_history, signal_channel_snapshots, species_signal_received,
+signal_sum_snapshots (downsampled 4x spatial signal for GIF). EcosystemMeasures gains 6 new
+fields: signal_total_history, signal_mass_fraction, signal_channel_snapshots,
+dominant_channel_history, receptor_alignment, emission_reception_matrix. All in summary.json.
+
+### Signal GIF
+
+signal.gif generated alongside ecosystem.gif using species-colored teal colormap.
+Mass/Signal tab toggle in ecosystem viewer. signal.gif checked in smoke_ecosystem.sh.
+
+### Viewer improvements
+
+Archive: SIGNAL badge, alpha/beta in creature modal, per-channel bar charts for signal params.
+Ecosystem: SIGNAL badge, outcome tooltips, signal charts sidebar, corrected mass chart label.
+Index: System tab anchor nav, quality metric section with formula, signal field section with
+diagram, signal descriptors in descriptor grid, SIGNAL/TORUS badges on run cards.
+docs/signal-field.svg: new diagram showing one-step signal mechanics with alpha/beta.
+
+---
+
+## v3.3.0 - 2026-04-18
+
+Signal field: per-creature emission and sensing in a shared (H,W,16) chemical field.
+
+Per-creature parameters: emission_vector (C,), receptor_profile (C,), signal_kernel (ring),
+emission_rate scalar, decay_rates (C,). --signal-field flag in CLI. Archive tagged
+signal_field: true/false in manifest.json. Quality filter updated for mass+signal conservation.
+Both homogeneous and heterogeneous ecosystem paths signal-aware. validate_signal_consistency()
+enforces archive compatibility (signal and non-signal archives cannot be mixed).
+
+---
+
+## v3.2.0 - 2026-04-18
+
+Temporal outcome classifier with separate taxonomies per run mode.
+
+Heterogeneous: merger, coexistence, exclusion, fragmentation -- now as temporal label sequence
+(list of OutcomeWindow with from_step, to_step, label) per species. Fragmentation uses patch
+count from v3.1.0 HeteroSpatial. Homogeneous taxonomy: full_merger, stable_isolation,
+partial_clustering, cannibalism, fragmentation -- all measurable from patch count dynamics.
+Outcome timeline visualization in ecosystem viewer. outcome_sequence stored in summary.json.
+
+---
+
+## v3.1.0 - 2026-04-18
+
+Spatial observables for both run modes from existing snapshot data (no new simulation code).
+
+Heterogeneous: patch count per species per snapshot, interface area per pair per snapshot,
+Euclidean COM distance per pair per snapshot, spatial entropy per species per snapshot,
+contact_occurred S×S bool matrix. Interaction coefficients gated to windows where
+interface_area > 0. 4-connected component labeling via scipy.ndimage.label.
+Homogeneous: patch count over time, mass spatial entropy, initial patch sizes, patch size
+distribution per snapshot. scipy declared as explicit dependency. HeteroSpatial /
+HomoSpatial typed dataclasses in analytics.py.
+
+---
+
 ## v3.0.0 - 2026-04-17
 
 Growth field capture, empirical interaction coefficients, ecosystem outcome classification, interaction heatmap in viewer.

README.md

@@ -156,20 +156,22 @@ This adds six signal parameters to each creature's searchable parameter space:
 | `receptor_profile` | `(16,)` | `[-1, 1]` | Channel weights for sensing. Negative values produce inhibitory (aversive) responses |
 | `emission_rate` | scalar | `[0.001, 0.05]` | Fraction of positive growth activity converted to signal per step. Lower values reduce mass bleed over long ecosystem runs |
 | `decay_rates` | `(16,)` | `[0, 0.9]` | Per-channel decay rate applied each step. Creatures with low decay on key channels maintain longer-range chemical gradients |
+| `alpha_coupling` | scalar | `[-1, 1]` | Reception-to-growth coupling. Positive = chemotaxis (grow into favorable signal, enables cross-species predation). Negative = chemorepulsion. Zero = no coupling |
+| `beta_modulation` | scalar | `[-1, 1]` | Adaptive emission. Positive = quorum sensing (amplify emission when receiving signal). Negative = feedback inhibition (suppress emission). Zero = static rate |
 | `signal_kernel_r` | scalar | `[0.2, 1.0]` | Signal kernel radius scale |
 | `signal_kernel_a/b/w` | `(3,)` each | same as mass kernels | Ring function parameters for signal diffusion |
 
 ![signal field mechanics](docs/signal-field.svg)
 
-**Physics.** At each step: (1) the creature emits signal proportional to local positive growth activity scaled by `emission_rate`, draining from the mass field into the signal field; (2) the signal field is convolved with the creature's signal kernel; (3) the dot product of the convolved field with `receptor_profile` boosts (or inhibits) the growth field; (4) the signal field decays per-channel at the creature's own `decay_rates`. The total conserved quantity is `mass + signal`. Decay is the only leak.
+**Physics.** At each step: (1) convolve mass to get G(H,W); (2) convolve signal field; (3) compute reception `dot(convolved_signal, receptor_profile)`; (4) apply `alpha_coupling`: `G *= (1 + alpha * reception).clamp(min=0)` -- positive alpha is chemotaxis (grow into favorable signal, including other species' territory, enabling cross-species predation); negative alpha is chemorepulsion; (5) modulate emission rate via `beta_modulation`: `rate_eff = rate * (1 + beta * mean(reception))` clipped to [0, 0.1] -- positive beta is quorum sensing, negative beta is feedback inhibition; (6) emit `G_pos * rate_eff * emission_vector`, draining mass into signal field; (7) reintegrate mass; (8) decay signal at `decay_rates`. Total conserved: mass + signal.
 
 **Archive compatibility.** An archive produced with `--signal-field` is tagged `"signal_field": true` in `manifest.json`. Ecosystem runs detect this automatically from the creature params -- no YAML flag needed. If any source creature comes from a signal-enabled archive, all sources must too; mixing signal and non-signal archives raises an error at load time.
 
 **Quality metric.** Three hard filters gate entry: (1) conserved mass within [0.5, 2.0] × initial; (2) bounding-box fraction < 0.6 (not scattered); (3) descriptor drift across adjacent 50-step windows ≤ 0.2. Survivors are ranked by a three-component score:
 
 ```
 non-signal:  q = 0.6 × compactness  +  0.4 × stability
-signal:      q = 0.5 × compactness  +  0.3 × stability  +  0.2 × retention
+signal:      q = 0.5 × compactness  +  0.2 × stability  +  0.3 × retention
 
 compactness = min( compact(state_T/2),  compact(state_T) )
 stability   = clip( 1 − drift / 0.2,  0,  1 )
@@ -283,7 +285,7 @@ ecosystem/20260415-104007-096-dense-population/
 ## Development
 
 ```bash
-just check       # ruff + pyright + pytest (401 tests, 0 warnings)
+just check       # ruff + pyright + pytest (422 tests, 0 warnings)
 just smoke-ray   # local-Ray integration smoke test
 ```
 
@@ -312,7 +314,9 @@ The test suite runs entirely in no-Ray mode. `just smoke-ray` exercises the Ray
   quality term; signal observables (total history, mass fraction, receptor alignment,
   emission-reception matrix); SIGNAL badge on archives; signal params in creature modal;
   signal overlay checkbox on ecosystem GIF; outcome label tooltips
-- [ ] v3.5.0 - Ecosystem viewer overhaul: all new charts, signal GIF overlay, mode-specific panels, temporal outcome sequence
+- [x] v3.5.0 - Chemical coupling (alpha_coupling [-1,1]: multiplicative growth, enables
+  cross-species predation) + adaptive emission (beta_modulation [-1,1]: quorum sensing /
+  feedback inhibition); 3 signal-only descriptors; descriptor library 15→18
 
 ## References