summaryrefslogtreecommitdiff
path: root/morphology/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'morphology/README.md')
-rw-r--r--morphology/README.md159
1 files changed, 159 insertions, 0 deletions
diff --git a/morphology/README.md b/morphology/README.md
new file mode 100644
index 0000000..b933f4a
--- /dev/null
+++ b/morphology/README.md
@@ -0,0 +1,159 @@
+# Meta-Affine Sequence Generator
+
+A Rust library for generating and validating meta-affine sequences.
+
+## Project Structure
+
+```
+morphology/
+├── meta_affine/ # Library source code
+│ ├── lib.rs # Public API and module exports
+│ ├── value.rs # Phase 1: Core data structures
+│ └── set.rs # Phase 2: Valid set generation
+├── tests/ # Test suite (separate from source)
+│ ├── value.rs # Tests for value module (16 tests)
+│ └── set.rs # Tests for set module (30 tests)
+├── examples/ # Example programs
+│ └── demo.rs # Comprehensive demonstration
+├── libmeta_affine.rlib # Compiled library
+└── README.md # This file
+```
+
+**Module:** `value.rs`
+
+Implements the foundation of meta-affine space:
+
+- Value struct representing (outer, inner) tuples
+- Compute minimum derivation path from (0,0) to any value
+- Five derivation rules for generating values
+
+**API:**
+```rust
+Value::new(outer, inner) -> Value
+Value::origin() -> Value
+Value::is_origin() -> bool
+get_minimum_derivation_path(value) -> Vec<Value>
+path_length(value) -> usize
+```
+
+**Module:** `set.rs`
+
+Implements downward-closed sets in meta-affine space:
+
+- ValidSet struct with validation
+- Set generation
+- Immutable set operations
+
+**API:**
+```rust
+ValidSet::new() -> ValidSet
+ValidSet::origin_set() -> ValidSet
+ValidSet::from_values(values) -> Result<ValidSet>
+ValidSet::add_value(value) -> Result<ValidSet>
+ValidSet::add_value_with_dependencies(value) -> ValidSet
+ValidSet::is_valid() -> bool
+ValidSet::contains(value) -> bool
+ValidSet::size() -> usize
+
+generate_valid_sets(max_size) -> Vec<ValidSet>
+generate_valid_sets_of_size(size) -> Vec<ValidSet>
+```
+
+## Building and Testing
+
+### Compile the Library
+
+```bash
+cd morphology
+rustc --crate-type=lib --crate-name=meta_affine --edition=2021 \
+ meta_affine/lib.rs --out-dir .
+```
+
+### Run Tests
+
+```bash
+# Compile value tests
+rustc --test --edition=2021 tests/value.rs -L . \
+ --extern meta_affine=libmeta_affine.rlib -o test_value
+
+# Compile set tests
+rustc --test --edition=2021 tests/set.rs -L . \
+ --extern meta_affine=libmeta_affine.rlib -o test_set
+
+# Run tests
+./test_value # 16 tests
+./test_set # 30 tests
+```
+
+### Run Demonstration
+
+```bash
+rustc examples/demo.rs -L . --extern meta_affine=libmeta_affine.rlib -o demo
+./demo
+```
+
+## Usage Examples
+
+### Core Data Structures
+
+```rust
+use meta_affine::{Value, value::get_minimum_derivation_path};
+
+// Create a value
+let v = Value::new(2, 3);
+
+// Get its minimum derivation path from origin
+let path = get_minimum_derivation_path(v);
+// [(0,0), (1,0), (2,0), (2,1), (2,2), (2,3)]
+
+// Check if it's the origin
+assert!(!v.is_origin());
+assert!(Value::origin().is_origin());
+```
+
+### Valid Set Generation
+
+```rust
+use meta_affine::{ValidSet, Value};
+use meta_affine::set::generate_valid_sets;
+
+// Create a set with automatic dependency inclusion
+let set = ValidSet::new()
+ .add_value_with_dependencies(Value::new(2, 3));
+// Contains: (0,0), (1,0), (2,0), (2,1), (2,2), (2,3)
+
+// Validate a set
+assert!(set.is_valid());
+assert_eq!(set.size(), 6);
+
+// Generate all valid sets up to size 5
+let all_sets = generate_valid_sets(5);
+// Returns 210 valid sets
+```
+
+## Mathematical Background
+
+### Meta-Affine Space
+
+A meta-affine space consists of 2-tuple values (outer, inner) satisfying:
+
+1. (0,0) is in the space
+2. If (n,0) is in, then (n+1,0) is in (increment outer)
+3. If (n,0) is in, then (n-1,0) is in (decrement outer)
+4. If (m,n) is in, then (m,n+1) is in (increment inner)
+5. If (m,n) is in, then (m,n-1) is in (decrement inner)
+
+### Valid Sets
+
+- For every value v ∈ S, all values in the minimum derivation path from (0,0) to v must be in S
+
+This creates a dependency structure ensuring sets are "closed" under derivation.
+
+### Valid Sequences
+
+A sequence is valid if it satisfies four constraints:
+1. Every value in the generating set appears at least once
+2. No value appears next to itself
+3. Last value is (0,0)
+4. For each outer value n, the last occurrence of any (n,m) has m=0
+