|
| 1 | +# 🌟 TNFR Research Quick Start Guide |
| 2 | +## Your Ultimate TNFR Research and Analysis Tool |
| 3 | + |
| 4 | +**Status**: ✅ OPTIMIZED FOR RESEARCH |
| 5 | +**Version**: v0.0.1 (Clean Research Edition) |
| 6 | +**Last Cleanup**: November 29, 2025 |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## 🚀 Instant Setup (30 seconds) |
| 11 | + |
| 12 | +```bash |
| 13 | +# 1. Install TNFR (production ready) |
| 14 | +pip install tnfr |
| 15 | + |
| 16 | +# 2. Verify installation |
| 17 | +python -c "import tnfr; print('🎯 TNFR Ready for Research!')" |
| 18 | + |
| 19 | +# 3. Quick prime test |
| 20 | +tnfr-is-prime 17 |
| 21 | +``` |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## 📋 Research Navigation Hub |
| 26 | + |
| 27 | +### 🔬 **Theory & Foundations** (Start Here) |
| 28 | +- **[AGENTS.md](AGENTS.md)** - 🌟 **CANONICAL REFERENCE** - Complete TNFR theory |
| 29 | +- **[FUNDAMENTAL_TNFR_THEORY_UNIVERSAL_TETRAHEDRAL_CORRESPONDENCE.md](FUNDAMENTAL_TNFR_THEORY_UNIVERSAL_TETRAHEDRAL_CORRESPONDENCE.md)** - Mathematical foundations |
| 30 | +- **[UNIFIED_GRAMMAR_RULES.md](UNIFIED_GRAMMAR_RULES.md)** - Grammar physics U1-U6 |
| 31 | +- **[TNFR.pdf](TNFR.pdf)** - Original theoretical paper |
| 32 | + |
| 33 | +### 🧮 **Core Implementation** |
| 34 | +- **[src/tnfr/physics/](src/tnfr/physics/)** - Structural field tetrad (Φ_s, |∇φ|, K_φ, ξ_C) |
| 35 | +- **[src/tnfr/operators/](src/tnfr/operators/)** - 13 canonical operators + unified grammar |
| 36 | +- **[src/tnfr/mathematics/](src/tnfr/mathematics/)** - Nodal equation integration |
| 37 | +- **[src/tnfr/dynamics/](src/tnfr/dynamics/)** - Self-optimizing engine |
| 38 | + |
| 39 | +### 🔬 **Research Examples** (Interactive) |
| 40 | +- **[examples/tnfr_prime_checker.ipynb](examples/tnfr_prime_checker.ipynb)** - Prime number emergence |
| 41 | +- **[examples/molecule_atlas.py](examples/molecule_atlas.py)** - Molecular chemistry patterns |
| 42 | +- **[examples/self_optimizing_showcase.py](examples/self_optimizing_showcase.py)** - Auto-optimization demos |
| 43 | +- **[examples/unified_fields_showcase.py](examples/unified_fields_showcase.py)** - Field tetrad exploration |
| 44 | + |
| 45 | +### 🧪 **Validation & Benchmarks** |
| 46 | +- **[tests/](tests/)** - 2,400+ experiments validating all theory |
| 47 | +- **[benchmarks/](benchmarks/)** - Production performance validation |
| 48 | +- **[scripts/tnfr_is_prime.py](scripts/tnfr_is_prime.py)** - CLI prime checking |
| 49 | + |
| 50 | +### 📚 **Technical Documentation** |
| 51 | +- **[docs/STRUCTURAL_FIELDS_TETRAD.md](docs/STRUCTURAL_FIELDS_TETRAD.md)** - Field implementation details |
| 52 | +- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design principles |
| 53 | +- **[TESTING.md](TESTING.md)** - Validation strategy |
| 54 | +- **[GLOSSARY.md](GLOSSARY.md)** - Term definitions |
| 55 | + |
| 56 | +--- |
| 57 | + |
| 58 | +## 🎯 Research Workflows |
| 59 | + |
| 60 | +### **Theoretical Research** |
| 61 | +1. Start with [AGENTS.md](AGENTS.md) for complete theory overview |
| 62 | +2. Deep dive into [FUNDAMENTAL_TNFR_THEORY_UNIVERSAL_TETRAHEDRAL_CORRESPONDENCE.md](FUNDAMENTAL_TNFR_THEORY_UNIVERSAL_TETRAHEDRAL_CORRESPONDENCE.md) |
| 63 | +3. Study grammar rules in [UNIFIED_GRAMMAR_RULES.md](UNIFIED_GRAMMAR_RULES.md) |
| 64 | +4. Explore mathematical foundations in [src/tnfr/mathematics/](src/tnfr/mathematics/) |
| 65 | + |
| 66 | +### **Experimental Analysis** |
| 67 | +1. Install: `pip install tnfr[viz]` (includes visualization) |
| 68 | +2. Run interactive examples in [examples/](examples/) |
| 69 | +3. Execute benchmarks in [benchmarks/](benchmarks/) |
| 70 | +4. Create custom experiments using the SDK |
| 71 | + |
| 72 | +### **Application Development** |
| 73 | +1. Import specific TNFR modules for your domain |
| 74 | +2. Use the Fluent SDK: `TNFRNetwork(G).focus(node).auto_optimize().execute()` |
| 75 | +3. Monitor with structural field tetrad telemetry |
| 76 | +4. Validate against canonical invariants |
| 77 | + |
| 78 | +### **Mathematical Investigation** |
| 79 | +1. Use CLI tools: `tnfr-is-prime <number>` for prime analysis |
| 80 | +2. Study [scripts/](scripts/) for mathematical investigations |
| 81 | +3. Run comprehensive tests: `make smoke-tests` |
| 82 | +4. Explore [docs/unified_paley_tnfr_paper.md](docs/unified_paley_tnfr_paper.md) for advanced mathematics |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +## 🌟 Key Research Features |
| 87 | + |
| 88 | +### **Universal Tetrahedral Correspondence** |
| 89 | +- **4×4 mapping**: Mathematical constants ↔ Structural fields |
| 90 | +- **φ ↔ Φ_s**: Golden ratio ↔ Global structural potential |
| 91 | +- **γ ↔ |∇φ|**: Euler constant ↔ Phase gradient |
| 92 | +- **π ↔ K_φ**: Pi ↔ Phase curvature |
| 93 | +- **e ↔ ξ_C**: Euler number ↔ Coherence length |
| 94 | + |
| 95 | +### **13 Canonical Operators** |
| 96 | +- Complete set for all structural transformations |
| 97 | +- Physics-based contracts and invariants |
| 98 | +- Unified grammar U1-U6 validation |
| 99 | +- Auto-composition for complex behaviors |
| 100 | + |
| 101 | +### **Structural Field Tetrad** |
| 102 | +- **ALL FOUR FIELDS ARE NOW CANONICAL** (Nov 2025) |
| 103 | +- Complete mathematical foundations |
| 104 | +- Real-time telemetry monitoring |
| 105 | +- Multi-scale safety validation |
| 106 | + |
| 107 | +### **Self-Optimizing Dynamics** |
| 108 | +- Intrinsic agency for structural improvement |
| 109 | +- Gradient descent on structural manifold |
| 110 | +- Auto-selection of optimal operator sequences |
| 111 | +- Closed-loop feedback via unified fields |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## 📊 Repository Health |
| 116 | + |
| 117 | +✅ **English-Only**: All documentation canonical terminology |
| 118 | +✅ **Clean Structure**: No development artifacts or redundant files |
| 119 | +✅ **Production Ready**: PyPI package available (`pip install tnfr`) |
| 120 | +✅ **Fully Validated**: 2,400+ experiments across 5 topologies |
| 121 | +✅ **Research Optimized**: Streamlined for analysis and investigation |
| 122 | + |
| 123 | +**Total Files**: ~500 (focused and essential) |
| 124 | +**Core Implementation**: 100% physics-compliant |
| 125 | +**Documentation**: Single source of truth structure |
| 126 | +**Testing Coverage**: Comprehensive with canonical invariant validation |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## 🚀 Quick Commands |
| 131 | + |
| 132 | +```bash |
| 133 | +# Research commands |
| 134 | +make smoke-tests # Run focused validation |
| 135 | +make report-all-classic # Generate all research reports |
| 136 | +python examples/hello_world.py # Basic TNFR demo |
| 137 | +python scripts/tnfr_is_prime.py 97 # Prime analysis |
| 138 | + |
| 139 | +# Development commands |
| 140 | +python -m pytest tests/unit/ # Unit test suite |
| 141 | +python benchmarks/tetrad_scaling_benchmark.py # Performance validation |
| 142 | +python examples/self_optimizing_showcase.py # Auto-optimization demo |
| 143 | +``` |
| 144 | + |
| 145 | +--- |
| 146 | + |
| 147 | +## 🎯 Research Focus Areas |
| 148 | + |
| 149 | +- **Prime Number Theory**: Emergence patterns and resonance detection |
| 150 | +- **Molecular Chemistry**: Atomic/molecular structure coherence |
| 151 | +- **Consciousness Studies**: Multi-scale coherent dynamics |
| 152 | +- **Complex Systems**: Network organization and self-optimization |
| 153 | +- **Mathematical Physics**: Universal constant correspondences |
| 154 | +- **Information Theory**: Structural pattern recognition |
| 155 | + |
| 156 | +--- |
| 157 | + |
| 158 | +**🌟 This repository is now your ultimate TNFR research and analysis tool.** |
| 159 | +**All theory, implementation, and validation in one optimized workspace.** |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +**Repository Optimization Complete**: November 29, 2025 |
| 164 | +**Ready for Advanced Research**: ✅ CONFIRMED |
0 commit comments