symbios 1.0.4

A derivation engine for L-Systems (ABOP compliant).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# Symbios

**A Sovereign Derivation Engine for Parametric L-Systems.**

Symbios is a pure-Rust, high-performance engine for generating Lindenmayer Systems. It is designed for "Sovereign" applications where the logic must run locally, deterministically, and safely (e.g., WASM environments, embedded simulation).

It fully implements the syntax and semantics described in *The Algorithmic Beauty of Plants* (Prusinkiewicz & Lindenmayer, 1990).

## Key Features

*   **Structure-of-Arrays (SoA)**: Data layout optimized for cache locality and WASM memory limits.
*   **Parametric & Context-Sensitive**: Full support for `(k,l)-systems`, arithmetic guards `A(x) : x > 5 -> ...`, and variable binding.
*   **Adversarial Hardening**: Protected against recursion bombs, memory exhaustion, and floating-point fragility.
*   **Deterministic**: Seedable RNG (`rand_pcg`) ensures reproducible procedural generation.

## Usage

```toml
[dependencies]
symbios = "1.0.2"
```

```rust
use symbios::System;

fn main() {
    let mut sys = System::new();
    
    // 1. Define Rules (ABOP Syntax)
    // A module 'A' with parameter 'x' grows if 'x' is small
    sys.add_rule("A(x) : x < 10 -> A(x + 1) B(x)").unwrap();
    
    // 2. Set Axiom
    sys.set_axiom("A(0)").unwrap();
    
    // 3. Derive
    sys.derive(5).unwrap();
    
    // 4. Inspect
    println!("{}", sys.state.display(&sys.interner));
}
```

## Performance

Symbios uses a flat memory arena for parameters and `u16` symbol interning.
*   **Rule Matching**: $O(N)$ (HashMap bucketed)
*   **Context Matching**: $O(1)$ (Topology Skip-Links)

See [PERFORMANCE.md](PERFORMANCE.md) for detailed benchmarks and optimization tips.

## Documentation

- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design, SoA layout, VM architecture, and design decisions
- **[PERFORMANCE.md](PERFORMANCE.md)** - Benchmark results, optimization tips, and profiling guide
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common errors, solutions, and debugging patterns

## Examples

See [examples/](examples/) for complete working examples:
- [anabaena.rs](examples/anabaena.rs) - Simple discrete L-System from ABOP
- [monopodial_tree.rs](examples/monopodial_tree.rs) - Complex tree with branches and constants
- [stochastic_decay.rs](examples/stochastic_decay.rs) - Stochastic rule demonstration
- [adaptive_plant.rs](examples/adaptive_plant.rs) - Advanced example with age, context, and environment

## License

MIT