Update MODEL_CARD.md

MODEL_CARD.md

@@ -1,308 +1,308 @@
----
-language: wolfram
-tags:
-- chaos-theory
-- mathematics
-- simulation
-- game-theory
-- fibonacci
-- bernoulli
-- nash-equilibrium
-- dynamical-systems
-license: mit
-library_name: chaossim
----
-
-# ChaosSim: Advanced Chaos Simulation Framework
-
-<div align="center">
-
-![ChaosSim](https://img.shields.io/badge/ChaosSim-v1.0-blue.svg)
-![Wolfram](https://img.shields.io/badge/Wolfram-Language-red.svg)
-![License](https://img.shields.io/badge/License-MIT-green.svg)
-
-*Simulating Randomized Chaotic Systems through Mathematical Principles*
-
-</div>
-
-## Model Description
-
-ChaosSim is a sophisticated chaos simulation framework built with Wolfram Programming Language that combines three fundamental mathematical concepts to model and visualize complex chaotic systems:
-
-1. **Bernoulli Numbers** - For probabilistic chaos modeling with weighted distributions
-2. **Fibonacci Sequences** - For self-similar patterns and golden ratio-based structures
-3. **Nash Equilibrium (Game Theory)** - For strategic interactions in multi-agent chaotic systems
-
-### Model Architecture
-
-The framework consists of four integrated components:
-
-- **Core Engine** (`ChaosSim.nb`) - Main simulation algorithms
-- **Mathematical Utilities** (`MathUtils.wl`) - Reusable mathematical functions package
-- **Visualization Suite** (`Visualizations.nb`) - Advanced plotting and analysis tools
-- **Examples Library** (`Examples.nb`) - 10+ practical demonstrations
-
-## Authors
-
-- **Andrew Magdy Kamal** - Lead Developer & Mathematician
-- **Riemann Computing Inc.** - Research & Development
-- **Openpeer AI** - AI Integration & Optimization
-
-## Intended Uses
-
-### Primary Use Cases
-
-1. **Academic Research**
-   - Chaos theory investigation
-   - Dynamical systems analysis
-   - Game theory simulations
-   - Mathematical modeling
-
-2. **Financial Modeling**
-   - Market volatility simulation
-   - Risk assessment using chaotic patterns
-   - Portfolio optimization with game theory
-
-3. **Complex Systems Analysis**
-   - Multi-agent behavior modeling
-   - Equilibrium state prediction
-   - Pattern recognition in chaotic data
-
-4. **Educational Purposes**
-   - Teaching chaos theory concepts
-   - Demonstrating mathematical principles
-   - Interactive learning environments
-
-### Out-of-Scope Uses
-
-- Real-time prediction systems (chaos is inherently unpredictable)
-- Critical infrastructure control (deterministic systems required)
-- Medical diagnosis (not validated for clinical use)
-- Financial advice (for research purposes only)
-
-## How to Use
-
-### Requirements
-
-- Wolfram Mathematica 12.0 or higher
-- Wolfram Engine or Wolfram Desktop
-- Basic understanding of chaos theory and mathematics
-
-### Quick Start
-
-```mathematica
-(* Load ChaosSim *)
-Get["ChaosSim.nb"]
-
-(* Generate Bernoulli-based chaos *)
-bernoulliData = SimulateBernoulliChaos[500, 12];
-PlotBernoulliChaos[bernoulliData]
-
-(* Create Fibonacci golden spiral *)
-spiralPoints = FibonacciSpiral3D[20, 100];
-Plot3DChaos[spiralPoints]
-
-(* Find Nash equilibrium *)
-payoff1 = {{3, 0}, {5, 1}};
-payoff2 = {{3, 5}, {0, 1}};
-equilibria = FindNashEquilibrium[payoff1, payoff2]
-
-(* Run unified chaos simulation *)
-unifiedChaos = UnifiedChaosSimulation[400];
-correlations = ChaosCorrelationAnalysis[unifiedChaos]
-```
-
-### Example: Multi-Agent Chaos System
-
-```mathematica
-(* Simulate 5 agents seeking equilibrium *)
-chaos = MultiAgentChaosEquilibrium[5, 200];
-
-(* Visualize agent behavior *)
-VisualizeMultiAgentChaos[5, 200]
-```
-
-### Example: Chaotic Market Simulation
-
-```mathematica
-(* Simulate 250 days of market chaos *)
-marketPrices = SimulateChaoticMarket[250, 100.0];
-
-(* Analyze price evolution *)
-ListLinePlot[marketPrices, 
-  PlotLabel -> "Chaotic Market Prices",
-  AxesLabel -> {"Day", "Price"}]
-```
-
-## Mathematical Foundation
-
-### Bernoulli Numbers
-
-Bernoulli numbers $B_n$ are used to create weighted probability distributions:
-
-$$B_0 = 1, \quad B_1 = -\frac{1}{2}, \quad B_2 = \frac{1}{6}, \quad B_4 = -\frac{1}{30}, \ldots$$
-
-The chaos weight function:
-
-$$w(n) = |B_n| \text{ (normalized)}$$
-
-### Fibonacci Sequences
-
-The Fibonacci sequence creates self-similar patterns:
-
-$$F_n = F_{n-1} + F_{n-2}, \quad F_0 = 0, F_1 = 1$$
-
-Golden ratio approximation:
-
-$$\phi \approx \lim_{n \to \infty} \frac{F_{n+1}}{F_n} = \frac{1 + \sqrt{5}}{2} \approx 1.618$$
-
-### Nash Equilibrium
-
-A strategy profile $(s_1^*, s_2^*)$ is a Nash equilibrium if:
-
-$$u_1(s_1^*, s_2^*) \geq u_1(s_1, s_2^*) \quad \forall s_1$$
-$$u_2(s_1^*, s_2^*) \geq u_2(s_1^*, s_2) \quad \forall s_2$$
-
-Where $u_i$ represents the utility function for player $i$.
-
-## Key Features
-
-### Chaos Generation Methods
-
-| Method | Description | Primary Use |
-|--------|-------------|-------------|
-| **BernoulliChaos** | Weighted probabilistic chaos | Non-uniform distributions |
-| **FibonacciChaos** | Golden ratio-based patterns | Natural chaotic structures |
-| **NashChaos** | Game-theoretic equilibrium | Multi-agent systems |
-| **UnifiedChaos** | Combined approach | Complex system modeling |
-
-### Analysis Tools
-
-- **Shannon Entropy** - Measure chaos complexity
-- **Lyapunov Exponent** - Quantify sensitivity to initial conditions
-- **Hurst Exponent** - Analyze long-range dependencies
-- **Correlation Dimension** - Determine fractal properties
-- **Phase Space Analysis** - Visualize attractor structures
-
-### Visualization Capabilities
-
-- 2D/3D time series plots
-- Phase space diagrams
-- Bifurcation diagrams
-- 3D attractors with color mapping
-- Interactive parameter exploration
-- Correlation matrices
-- Multi-agent behavior tracking
-
-## Performance Metrics
-
-### Computational Efficiency
-
-| Simulation Type | 1000 Iterations | 10000 Iterations |
-|----------------|-----------------|------------------|
-| Bernoulli Chaos | ~0.5s | ~2.5s |
-| Fibonacci Chaos | ~0.3s | ~1.8s |
-| Nash Equilibrium | ~1.2s | ~8.5s |
-| Unified Chaos | ~2.0s | ~12s |
-
-*Benchmarked on Wolfram Mathematica 13.0, Intel i7-11800H, 16GB RAM*
-
-### Chaos Quality Metrics
-
-ChaosSim generates high-quality chaotic sequences with:
-- Lyapunov exponents: 0.3 - 0.8 (positive, indicating chaos)
-- Shannon entropy: 3.5 - 4.8 bits (high unpredictability)
-- Correlation dimension: 1.5 - 2.8 (fractal properties)
-
-## Limitations
-
-1. **Computational Intensity**: Large-scale simulations (>50,000 iterations) may require significant computational resources
-2. **Deterministic Chaos**: While unpredictable, the system is deterministic - same initial conditions yield same results
-3. **Approximations**: Bernoulli numbers use finite precision arithmetic
-4. **Game Theory Constraints**: Nash equilibrium finder currently supports pure strategies in finite games
-5. **Platform Dependency**: Requires Wolfram Mathematica (proprietary software)
-
-## Ethical Considerations
-
-### Responsible Use
-
-- **Financial Applications**: ChaosSim should not be used as the sole basis for investment decisions
-- **Research Integrity**: Results should be validated against established chaos theory literature
-- **Educational Context**: Clearly distinguish between theoretical models and real-world predictions
-- **Reproducibility**: Document random seeds and parameters for reproducible research
-
-### Potential Risks
-
-- **Misinterpretation**: Chaotic patterns may appear to have predictive power but are fundamentally uncertain
-- **Over-reliance**: Users should not depend solely on chaotic models for critical decisions
-- **Complexity Bias**: Complex visualizations may create false confidence in understanding
-
-## Training Details
-
-### Development Process
-
-ChaosSim was developed using:
-- Classical chaos theory principles from Lorenz, Mandelbrot, and Poincaré
-- Game theory foundations from Nash and von Neumann
-- Numerical methods validated against peer-reviewed literature
-- Extensive testing against known chaotic systems (Lorenz attractor, logistic map)
-
-### Validation
-
-The framework has been validated by:
-- Comparing Lyapunov exponents with theoretical predictions
-- Verifying Nash equilibria against manual calculations
-- Testing Fibonacci convergence to golden ratio
-- Cross-validation with established chaos simulation tools
-
-## Environmental Impact
-
-ChaosSim is computationally efficient and designed for local execution, minimizing cloud computing environmental costs. Typical simulations consume minimal energy (< 0.1 kWh per 1000 runs).
-
-## Citation
-
-```bibtex
-@software{chaossim2025,
-  title = {ChaosSim: Advanced Chaos Simulation Framework},
-  author = {Kamal, Andrew Magdy and {Riemann Computing Inc.} and {Openpeer AI}},
-  year = {2025},
-  month = {11},
-  version = {1.0},
-  url = {http://huggingface.co/OpenPeerAI/ChaosSim},
-  license = {MIT}
-}
-```
-
-## Additional Resources
-
-### Documentation
-
-- `README.md` - Quick start guide and overview
-- `Examples.nb` - 10 practical examples with explanations
-- `Visualizations.nb` - Visualization function reference
-
-### Related Literature
-
-1. Lorenz, E. N. (1963). "Deterministic Nonperiodic Flow"
-2. Mandelbrot, B. B. (1982). "The Fractal Geometry of Nature"
-3. Nash, J. F. (1950). "Equilibrium Points in N-Person Games"
-4. Strogatz, S. H. (2015). "Nonlinear Dynamics and Chaos"
-
-## License
-
-MIT Licens - See LICENSE file for details
-
-## Acknowledgments
-
-Special thanks to:
-- The Wolfram Research team for the exceptional Wolfram Language
-- Game theory pioneers Nash, von Neumann, and Morgenstern
-- Open source mathematics community
-
----
-
-**Version**: 1.0.0  
-**Release Date**: November 25, 2025  
-**Maintainers**: Andrew Magdy Kamal, Riemann Computing Inc., Openpeer AI
-
-*For questions, feedback, or collaboration inquiries, please open a discussion post on Huggingface or contact the authors.*
+---
+language: wolfram
+tags:
+- chaos-theory
+- mathematics
+- simulation
+- game-theory
+- fibonacci
+- bernoulli
+- nash-equilibrium
+- dynamical-systems
+license: mit
+library_name: chaossim
+---
+
+# ChaosSim: Advanced Chaos Simulation Framework
+
+<div align="center">
+
+![ChaosSim](https://img.shields.io/badge/ChaosSim-v1.0-blue.svg)
+![Wolfram](https://img.shields.io/badge/Wolfram-Language-red.svg)
+![License](https://img.shields.io/badge/License-MIT-green.svg)
+
+*Simulating Randomized Chaotic Systems through Mathematical Principles*
+
+</div>
+
+## Model Description
+
+ChaosSim is a sophisticated chaos simulation framework built with the Wolfram Programming Language that combines three fundamental mathematical concepts to model and visualize complex chaotic systems:
+
+1. **Bernoulli Numbers** - For probabilistic chaos modeling with weighted distributions
+2. **Fibonacci Sequences** - For self-similar patterns and golden ratio-based structures
+3. **Nash Equilibrium (Game Theory)** - For strategic interactions in multi-agent chaotic systems
+
+### Model Architecture
+
+The framework consists of four integrated components:
+
+- **Core Engine** (`ChaosSim.nb`) - Main simulation algorithms
+- **Mathematical Utilities** (`MathUtils.wl`) - Reusable mathematical functions package
+- **Visualization Suite** (`Visualizations.nb`) - Advanced plotting and analysis tools
+- **Examples Library** (`Examples.nb`) - 10+ practical demonstrations
+
+## Authors
+
+- **Andrew Magdy Kamal** - Lead Developer & Mathematician
+- **Riemann Computing Inc.** - Research & Development
+- **Openpeer AI** - AI Integration & Optimization
+
+## Intended Uses
+
+### Primary Use Cases
+
+1. **Academic Research**
+   - Chaos theory investigation
+   - Dynamical systems analysis
+   - Game theory simulations
+   - Mathematical modeling
+
+2. **Financial Modeling**
+   - Market volatility simulation
+   - Risk assessment using chaotic patterns
+   - Portfolio optimization with game theory
+
+3. **Complex Systems Analysis**
+   - Multi-agent behavior modeling
+   - Equilibrium state prediction
+   - Pattern recognition in chaotic data
+
+4. **Educational Purposes**
+   - Teaching chaos theory concepts
+   - Demonstrating mathematical principles
+   - Interactive learning environments
+
+### Out-of-Scope Uses
+
+- Real-time prediction systems (chaos is inherently unpredictable)
+- Critical infrastructure control (deterministic systems required)
+- Medical diagnosis (not validated for clinical use)
+- Financial advice (for research purposes only)
+
+## How to Use
+
+### Requirements
+
+- Wolfram Mathematica 12.0 or higher
+- Wolfram Engine or Wolfram Desktop
+- Basic understanding of chaos theory and mathematics
+
+### Quick Start
+
+```mathematica
+(* Load ChaosSim *)
+Get["ChaosSim.nb"]
+
+(* Generate Bernoulli-based chaos *)
+bernoulliData = SimulateBernoulliChaos[500, 12];
+PlotBernoulliChaos[bernoulliData]
+
+(* Create Fibonacci golden spiral *)
+spiralPoints = FibonacciSpiral3D[20, 100];
+Plot3DChaos[spiralPoints]
+
+(* Find Nash equilibrium *)
+payoff1 = {{3, 0}, {5, 1}};
+payoff2 = {{3, 5}, {0, 1}};
+equilibria = FindNashEquilibrium[payoff1, payoff2]
+
+(* Run unified chaos simulation *)
+unifiedChaos = UnifiedChaosSimulation[400];
+correlations = ChaosCorrelationAnalysis[unifiedChaos]
+```
+
+### Example: Multi-Agent Chaos System
+
+```mathematica
+(* Simulate 5 agents seeking equilibrium *)
+chaos = MultiAgentChaosEquilibrium[5, 200];
+
+(* Visualize agent behavior *)
+VisualizeMultiAgentChaos[5, 200]
+```
+
+### Example: Chaotic Market Simulation
+
+```mathematica
+(* Simulate 250 days of market chaos *)
+marketPrices = SimulateChaoticMarket[250, 100.0];
+
+(* Analyze price evolution *)
+ListLinePlot[marketPrices, 
+  PlotLabel -> "Chaotic Market Prices",
+  AxesLabel -> {"Day", "Price"}]
+```
+
+## Mathematical Foundation
+
+### Bernoulli Numbers
+
+Bernoulli numbers $B_n$ are used to create weighted probability distributions:
+
+$$B_0 = 1, \quad B_1 = -\frac{1}{2}, \quad B_2 = \frac{1}{6}, \quad B_4 = -\frac{1}{30}, \ldots$$
+
+The chaos weight function:
+
+$$w(n) = |B_n| \text{ (normalized)}$$
+
+### Fibonacci Sequences
+
+The Fibonacci sequence creates self-similar patterns:
+
+$$F_n = F_{n-1} + F_{n-2}, \quad F_0 = 0, F_1 = 1$$
+
+Golden ratio approximation:
+
+$$\phi \approx \lim_{n \to \infty} \frac{F_{n+1}}{F_n} = \frac{1 + \sqrt{5}}{2} \approx 1.618$$
+
+### Nash Equilibrium
+
+A strategy profile $(s_1^*, s_2^*)$ is a Nash equilibrium if:
+
+$$u_1(s_1^*, s_2^*) \geq u_1(s_1, s_2^*) \quad \forall s_1$$
+$$u_2(s_1^*, s_2^*) \geq u_2(s_1^*, s_2) \quad \forall s_2$$
+
+Where $u_i$ represents the utility function for player $i$.
+
+## Key Features
+
+### Chaos Generation Methods
+
+| Method | Description | Primary Use |
+|--------|-------------|-------------|
+| **BernoulliChaos** | Weighted probabilistic chaos | Non-uniform distributions |
+| **FibonacciChaos** | Golden ratio-based patterns | Natural chaotic structures |
+| **NashChaos** | Game-theoretic equilibrium | Multi-agent systems |
+| **UnifiedChaos** | Combined approach | Complex system modeling |
+
+### Analysis Tools
+
+- **Shannon Entropy** - Measure chaos complexity
+- **Lyapunov Exponent** - Quantify sensitivity to initial conditions
+- **Hurst Exponent** - Analyze long-range dependencies
+- **Correlation Dimension** - Determine fractal properties
+- **Phase Space Analysis** - Visualize attractor structures
+
+### Visualization Capabilities
+
+- 2D/3D time series plots
+- Phase space diagrams
+- Bifurcation diagrams
+- 3D attractors with color mapping
+- Interactive parameter exploration
+- Correlation matrices
+- Multi-agent behavior tracking
+
+## Performance Metrics
+
+### Computational Efficiency
+
+| Simulation Type | 1000 Iterations | 10000 Iterations |
+|----------------|-----------------|------------------|
+| Bernoulli Chaos | ~0.5s | ~2.5s |
+| Fibonacci Chaos | ~0.3s | ~1.8s |
+| Nash Equilibrium | ~1.2s | ~8.5s |
+| Unified Chaos | ~2.0s | ~12s |
+
+*Benchmarked on Wolfram Mathematica 13.0, Intel i7-11800H, 16GB RAM*
+
+### Chaos Quality Metrics
+
+ChaosSim generates high-quality chaotic sequences with:
+- Lyapunov exponents: 0.3 - 0.8 (positive, indicating chaos)
+- Shannon entropy: 3.5 - 4.8 bits (high unpredictability)
+- Correlation dimension: 1.5 - 2.8 (fractal properties)
+
+## Limitations
+
+1. **Computational Intensity**: Large-scale simulations (>50,000 iterations) may require significant computational resources
+2. **Deterministic Chaos**: While unpredictable, the system is deterministic - same initial conditions yield same results
+3. **Approximations**: Bernoulli numbers use finite precision arithmetic
+4. **Game Theory Constraints**: Nash equilibrium finder currently supports pure strategies in finite games
+5. **Platform Dependency**: Requires Wolfram Mathematica (proprietary software)
+
+## Ethical Considerations
+
+### Responsible Use
+
+- **Financial Applications**: ChaosSim should not be used as the sole basis for investment decisions
+- **Research Integrity**: Results should be validated against established chaos theory literature
+- **Educational Context**: Clearly distinguish between theoretical models and real-world predictions
+- **Reproducibility**: Document random seeds and parameters for reproducible research
+
+### Potential Risks
+
+- **Misinterpretation**: Chaotic patterns may appear to have predictive power but are fundamentally uncertain
+- **Over-reliance**: Users should not depend solely on chaotic models for critical decisions
+- **Complexity Bias**: Complex visualizations may create false confidence in understanding
+
+## Training Details
+
+### Development Process
+
+ChaosSim was developed using:
+- Classical chaos theory principles from Lorenz, Mandelbrot, and Poincaré
+- Game theory foundations from Nash and von Neumann
+- Numerical methods validated against peer-reviewed literature
+- Extensive testing against known chaotic systems (Lorenz attractor, logistic map)
+
+### Validation
+
+The framework has been validated by:
+- Comparing Lyapunov exponents with theoretical predictions
+- Verifying Nash equilibria against manual calculations
+- Testing Fibonacci convergence to golden ratio
+- Cross-validation with established chaos simulation tools
+
+## Environmental Impact
+
+ChaosSim is computationally efficient and designed for local execution, minimizing cloud computing environmental costs. Typical simulations consume minimal energy (< 0.1 kWh per 1000 runs).
+
+## Citation
+
+```bibtex
+@software{chaossim2025,
+  title = {ChaosSim: Advanced Chaos Simulation Framework},
+  author = {Kamal, Andrew Magdy and {Riemann Computing Inc.} and {Openpeer AI}},
+  year = {2025},
+  month = {11},
+  version = {1.0},
+  url = {http://huggingface.co/OpenPeerAI/ChaosSim},
+  license = {MIT}
+}
+```
+
+## Additional Resources
+
+### Documentation
+
+- `README.md` - Quick start guide and overview
+- `Examples.nb` - 10 practical examples with explanations
+- `Visualizations.nb` - Visualization function reference
+
+### Related Literature
+
+1. Lorenz, E. N. (1963). "Deterministic Nonperiodic Flow"
+2. Mandelbrot, B. B. (1982). "The Fractal Geometry of Nature"
+3. Nash, J. F. (1950). "Equilibrium Points in N-Person Games"
+4. Strogatz, S. H. (2015). "Nonlinear Dynamics and Chaos"
+
+## License
+
+MIT Licens - See LICENSE file for details
+
+## Acknowledgments
+
+Special thanks to:
+- The Wolfram Research team for the exceptional Wolfram Language
+- Game theory pioneers Nash, von Neumann, and Morgenstern
+- Open source mathematics community
+
+---
+
+**Version**: 1.0.0  
+**Release Date**: November 25, 2025  
+**Maintainers**: Andrew Magdy Kamal, Riemann Computing Inc., Openpeer AI
+
+*For questions, feedback, or collaboration inquiries, please open a discussion post on Huggingface or contact the authors.*