Struct PatchTree 

pub struct PatchTree {
    pub amp: AmpEnv,
    pub root: AudioNode,
}

A complete patch genome: an audio term wrapped in the mandatory voice stage (amp ADSR → VCA → limiter → stereo out, added by the compiler).

Fields

amp: AmpEnv

Amplitude envelope parameters.

root: AudioNode

The evolved audio-term tree.

Implementations

impl PatchTree

pub fn domain_violations(&self) -> Vec<(String, f64)>

Every continuous site of this term that sits outside PARAM_DOMAIN, as (trace address, value), in address order.

Reads the trace, not the term, and that is the whole point: the trace enumerates exactly the continuous sites, by construction, from the same walk the prior samples. A hand-written match over 26 productions would be a second table of “which fields are knobs” — and the first module somebody forgot to add to it would be the one the next sentinel escaped through.

pub fn clamp_domains(&mut self) -> usize

Pull every out-of-domain continuous site back into PARAM_DOMAIN. Returns how many sites were repaired (0 = the term was already clean, and nothing was rebuilt).

Repair, not refusal, and the asymmetry is deliberate. A term over the size/depth ceilings cannot be fixed without deciding which modules to delete, so those are refused. A knob outside its range can be fixed, exactly and locally, and the alternative — refusing — would mean a saved session that already contains one becomes an app the player cannot edit, load or evolve their way out of. Corruption must not be load-bearing.

NaN clamps to the middle of the range rather than to an end: it carries no information about which way it went, and pinning it to a boundary would state one.

Identities survive. The rebuild goes through the trace, which does not carry uids, so the repaired term inherits them back from the term it replaced — same rule, and the same reason, as crate::set_param.

impl PatchTree

pub fn site_count(&self) -> usize

Total probabilistic-choice sites (amp envelope + tree).

pub fn signature(&self) -> String

Short human-readable signature along the main signal spine (saw·ladr·dly) — the default display name for unnamed patches.

pub fn to_sexpr(&self) -> String

Compact s-expression rendering for logs and tests.

pub fn ensure_uids(&mut self)

Give every node that still lacks an identity a fresh one, and break any duplicates.

This is the settle step: the point at which an anonymous tree becomes a thing a person can point at. Call it wherever a tree is adopted — admitted to the pool, put on the bench, restored from a save, arrived from the panel — and nowhere in the middle of search.

De-duplication is not paranoia. A whole-tree replace from the panel is arbitrary client JSON, and the one gesture that most obviously produces a repeat is “duplicate this module”: copying a subtree copies its uids, and two nodes claiming one identity is worse than no identity at all — a lock on either would light both. First occurrence in walk order keeps the id; the copies are minted fresh.

pub fn clear_uids(&mut self)

Strip every identity back to Uid::NEW.

Used where a tree must hash or serialize as pure content — the render memo’s key, above all, which would otherwise miss on every refinement step and invalidate every persisted row the moment uids started moving.

pub fn inherit_uids(&mut self, parent: &PatchTree)

Carry parent’s identities onto this tree wherever the structure is unchanged.

This is what makes locks and hand positions survive ⚡ evolve. Refinement does not mutate a tree in place — EvolutionChain proposes over the trace, and every accepted step reconstructs the whole genome through crate::genome’s decoder, which knows nothing about uids and cannot: a trace is a map from address to value. So a refined child comes back structurally near-identical to its seed and completely anonymous, and without this pass every generation would look to the UI like a brand new patch — the exact failure (R6) that would make pinned routings and freeform layout read as broken.

The match is positional and shallow-by-variant: walking both trees in lockstep, a node inherits its counterpart’s identity only if it is the same variant, but the walk descends either way. That last part matters — a step that swaps one filter for a reverb should not orphan the entire chain beneath it, which was not touched.

Anything left unmatched (a genuinely new module, a branch that grew) stays Uid::NEW and is minted by the following Self::ensure_uids.

Trait Implementations

impl Clone for PatchTree

fn clone(&self) -> PatchTree

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PatchTree

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PatchTree

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl EvolutionaryGenome for PatchTree

fn generate<R: Rng>(rng: &mut R, _bounds: &MultiBounds) -> Self

Draws from the default grammar configuration; bounds is ignored (this genome has no numeric-box structure). Prefer PatchGrammarPrior::sample_with_rng to control the grammar.

fn distance(&self, other: &Self) -> f64

Structural distance: parameter L1 where the trees agree, and a subtree-size penalty where they diverge. Defined for any pair (never panics); a heuristic for diversity mechanisms, not a metric with audio-perceptual meaning.

type Allele = f64

The allele type for individual genes

type Phenotype = PatchTree

The phenotype or decoded solution type

fn decode(&self) -> Self::Phenotype

Decode genome into phenotype for fitness evaluation

fn dimension(&self) -> usize

Compute dimensionality for adaptive operators

fn try_distance(&self, other: &Self) -> Result<f64, GenomeError>

Fallible distance metric.

fn as_slice(&self) -> Option<&[Self::Allele]>

Get the genome’s genes as a slice (for numeric genomes)

fn as_mut_slice(&mut self) -> Option<&mut [Self::Allele]>

Get the genome’s genes as a mutable slice (for numeric genomes)

impl PartialEq for PatchTree

fn eq(&self, other: &PatchTree) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for PatchTree

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TraceGenome for PatchTree

fn to_trace(&self) -> Trace

Convert genome to a fugue trace.

fn from_trace(trace: &Trace) -> Result<Self, GenomeError>

Reconstruct genome from a fugue trace.

fn trace_prefix() -> &'static str

Get the address prefix used for trace storage (default: "gene").

impl StructuralPartialEq for PatchTree