AGENTS.md@docs/other/quadray · git:20260906.82c8031 · 2026-09-06 · sha256 c840ec9f5aa330ae
AGENTS.md@docs/other/quadray git:20260906.82c8031A
Immutable. This exact content is served forever at /api/v1/blob/c840ec9f5aa330ae.
# Quadray Documentation Agent
> **📋 Document Metadata**
> **Type**: Geometric Framework Integration Agent | **Audience**: Researchers, Mathematicians | **Complexity**: Advanced
> **Cross-References**: [README.md](README.md) | [Quadray GNN Guide](quadray_gnn.md) | [Quadray Overview](quadray.md) | [Advanced Patterns](../../gnn/advanced/advanced_modeling_patterns.md) | [Main Documentation](../README.md)
## Overview
This directory contains comprehensive documentation, resources, and implementation guides for integrating **Quadray Coordinates** with GNN (Generalized Notation Notation). Quadray coordinates provide a tetrahedral coordinate system rooted in R. Buckminster Fuller's Synergetics, offering a natural geometric foundation for representing Active Inference state spaces.
**Status**: ✅ Production Ready
**Version**: 1.0
## Purpose
Quadray integration enables:
- **Geometric State Spaces**: Natural representation of Active Inference state spaces
- **Spatial Priors**: Simplified Dirichlet priors in navigation models
- **Transformation Matrices**: Direct mapping of 3D movements to GNN policies
- **Hierarchical Structures**: Representation of complex geometric relationships
- **4D Spatial Perspective**: Tetrahedral basis for probability space visualization
## Contents
**Files**: 5 | **Subdirectories**: 1
### Core Documentation Files
- **`README.md`**: Directory overview and navigation
- **`AGENTS.md`**: Technical documentation and agent scaffolding (this file)
- **`quadray_gnn.md`**: Complete Quadray-GNN integration guide
- **`quadray.md`**: Quadray coordinate system overview
## Quick Navigation
### This Directory
- **[README.md](README.md)**: Directory overview
- **[AGENTS.md](AGENTS.md)**: Technical documentation (this file)
- **[quadray_gnn.md](quadray_gnn.md)**: Complete integration guide
- **[quadray.md](quadray.md)**: Quadray coordinate system overview
### Main Documentation
- **[doc/README.md](../README.md)**: Main documentation hub
- **[CROSS_REFERENCE_INDEX.md](../../CROSS_REFERENCE_INDEX.md)**: Complete cross-reference index
- **[learning_paths.md](../../learning_paths.md)**: Learning pathways
### Related Directories
- **[Advanced Patterns](../../gnn/advanced/advanced_modeling_patterns.md)**: Advanced modeling techniques
- **[Mathematical Foundations](../../gnn/advanced/advanced_modeling_patterns.md#geometric-foundations)**: Geometric modeling
- **[Spatial Models](../../CROSS_REFERENCE_INDEX.md#spatial-modeling)**: Spatial modeling approaches
### Pipeline Integration
- **[Pipeline Documentation](../../gnn/operations/gnn_tools.md)**: Complete pipeline guide
- **[src/gnn/AGENTS.md](../../../src/gnn/AGENTS.md)**: Implementation details
## Technical Documentation
### Quadray Coordinate System Architecture
Quadray coordinates provide:
#### 4D Spatial Perspective
- **Tetrahedral Basis**: Four coordinates derived from regular tetrahedron
- **Natural Symmetry**: Symmetry for close-packed arrangements
- **Integer Coordinates**: Integer coordinates for many geometric configurations
- **Redundant Representation**: Flexible normalization capabilities
#### Mathematical Foundation
A point in three-dimensional space is represented by a 4-tuple $(a,b,c,d)$ where:
$$\vec{r} = a\vec{e}_a + b\vec{e}_b + c\vec{e}_c + d\vec{e}_d$$
with tetrahedral basis vectors satisfying:
$$\vec{e}_a + \vec{e}_b + \vec{e}_c + \vec{e}_d = \vec{0}$$
### Integration Points
#### GNN Model Representation
- **State Space Encoding**: Quadray coordinates for state factor representation
- **Spatial Prior Encoding**: Simplified Dirichlet priors using Quadray symmetry
- **Transformation Matrices**: Direct mapping of 3D movements to GNN policies
- **Hierarchical Structures**: Natural representation of complex geometric relationships
#### Normalization Schemes
- **Probability Normalization**: For representing probability distributions
- **Zero-Minimum Normalization**: For computational efficiency
- **Barycentric Normalization**: For weighted combinations in tetrahedral structures
## Integration with Pipeline
This documentation is integrated with the 25-step GNN processing pipeline:
### Core Processing (Steps 0-9)
- **Step 3 (GNN)**: Quadray coordinate representation in parsed GNN models
- **Step 5 (Type Checker)**: Geometric validation of Quadray coordinates
- **Step 6 (Validation)**: Validation of spatial prior encoding
- **Step 7 (Export)**: Quadray coordinate export in multi-format outputs
### Simulation (Steps 10-16)
- **Step 11 (Render)**: Quadray-based spatial modeling in code generation
- **Step 12 (Execute)**: Geometric transformation execution
- **Step 16 (Analysis)**: Geometric analysis of Quadray representations
### Integration (Steps 17-24)
- **Step 8 (Visualization)**: Quadray coordinate visualization
- **Step 23 (Report)**: Geometric analysis and visualization results
See [src/gnn/AGENTS.md](../../../src/gnn/AGENTS.md) for complete pipeline documentation.
## Function Signatures and API
### Coordinate Transformation Functions
```python
def transform_to_quadray_coordinates(cartesian_point: np.ndarray) -> QuadrayCoords:
"""
Transform Cartesian coordinates to Quadray coordinates.
Parameters:
cartesian_point: 3D point in Cartesian coordinates (x, y, z)
Returns:
QuadrayCoords 4-tuple (a, b, c, d)
"""
def apply_quadray_transformation(
gnn_model: GNNModel, transformation: QuadrayMatrix
) -> GNNModel:
"""
Apply Quadray transformation to GNN model state space.
Parameters:
gnn_model: Parsed GNN model structure
transformation: Quadray transformation matrix
Returns:
Transformed GNNModel with Quadray coordinate representation
"""
def encode_spatial_prior(
quadray_coords: QuadrayCoords, prior_type: str
) -> DirichletPrior:
"""
Encode spatial prior using Quadray symmetry.
Parameters:
quadray_coords: Quadray coordinate representation
prior_type: Type of prior encoding (probability, zero-minimum, barycentric)
Returns:
DirichletPrior with simplified encoding
"""
```
## Standards and Guidelines
All documentation in this module adheres to professional standards:
- **Clarity**: Concrete, technical writing with geometric foundations
- **Functionality**: Describes actual Quadray integration capabilities
- **Completeness**: Comprehensive coverage of geometric coordinate integration
- **Consistency**: Uniform structure and style with GNN documentation ecosystem
## Related Resources
### Main GNN Documentation
- **[GNN Overview](../../gnn/gnn_overview.md)**: Core GNN concepts
- **[GNN Quickstart](../../gnn/tutorials/quickstart_tutorial.md)**: Getting started guide
- **[Advanced Patterns](../../gnn/advanced/advanced_modeling_patterns.md)**: Advanced modeling techniques
### Geometric Resources
- **[Mathematical Foundations](../../gnn/advanced/advanced_modeling_patterns.md#geometric-foundations)**: Geometric modeling
- **[Spatial Models](../../CROSS_REFERENCE_INDEX.md#spatial-modeling)**: Spatial modeling approaches
- **[Advanced Patterns](../../gnn/advanced/advanced_modeling_patterns.md)**: Advanced modeling techniques
### Pipeline Architecture
- **[Pipeline Documentation](../../gnn/operations/gnn_tools.md)**: Complete pipeline guide
- **[Pipeline AGENTS](../../../src/gnn/AGENTS.md)**: Implementation details
- **[Pipeline README](../../../src/gnn/README.md)**: Pipeline overview
## See Also
- **[Quadray Cross-Reference](../../CROSS_REFERENCE_INDEX.md#quadray)**: Cross-reference index entry
- **[Advanced Patterns](../../gnn/advanced/advanced_modeling_patterns.md)**: Related advanced modeling techniques
- **[Mathematical Foundations](../../gnn/advanced/advanced_modeling_patterns.md#geometric-foundations)**: Geometric modeling
- **[Main Index](../README.md)**: Return to main documentation
---
**Status**: ✅ Production Ready
**Compliance**: Professional documentation standards
**Maintenance**: Regular updates with new Quadray features and integration capabilities