Upload README.md

README.md

@@ -1,14 +1,73 @@
----
-title: EmergentRFT Space
-emoji: 🏢
-colorFrom: green
-colorTo: green
-sdk: gradio
-sdk_version: 6.0.0
-app_file: app.py
-pinned: false
-license: other
-short_description: uncover complex system dynamics and emergent phenomena using
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# EmergentRFT-Space: Interactive Render Frame Theory Simulation
+
+**Explore complex adaptive systems and emergent behaviors with a high-performance, interactive RFT simulator.**
+
+This Hugging Face Space hosts an interactive Gradio application that allows users to experiment with the Render Frame Theory (RFT) simulation. RFT is a computational framework designed to model dynamic systems exhibiting non-linear interactions and emergent properties.
+
+## ✨ Key Features
+
+-   **Interactive Parameters**: Adjust key RFT parameters (`Ncells`, `Nmode`, `Iterations`, `dt`, `eps`, `sigma`, `theta`, `k_shred`) using intuitive sliders.
+-   **High-Performance Backend**: Automatically utilizes CUDA/CuPy for GPU acceleration if available, otherwise gracefully falls back to an optimized PyTorch/NumPy CPU implementation.
+-   **Dynamic Visualizations**: Observe the system's evolution through real-time plots of mean `m_root`, mean `A_modes`, and cumulative 'shredding' events over iterations.
+-   **Performance Metrics**: Get an estimated GFLOPS (Giga Floating-point Operations Per Second) metric with each simulation run to quantify computational throughput.
+-   **Breakthrough Explanation**: Learn about RFT's novel approach, the significance of its 'shredding' mechanism, dynamic feedback loops, scalability, and versatility.
+-   **Example Scenario**: Understand RFT's applicability through a concrete example of modeling cascading failures in financial markets.
+
+## 💡 What is Render Frame Theory (RFT)?
+
+Render Frame Theory (RFT) is a computational framework for simulating complex adaptive systems, often involving emergent properties and non-linear dynamics. It models a system as a collection of 'cells', each with internal 'modes' that evolve over time based on coupled differential equations.
+
+### Key Components:
+*   **MOMKernel**: This class acts as a high-performance computational engine. When a CUDA-enabled GPU is available, it compiles and executes a custom **CUDA kernel** (`fused_mom_update`) to perform core mathematical updates in parallel. If CUDA is not available or compilation fails, it gracefully falls back to a **pure PyTorch/NumPy CPU implementation** (`fused_mom_update_cpu`).
+*   **MOMSystemLoop**: Manages the iterative simulation process, repeatedly calling the `MOMKernel` and applying a `feedback` mechanism that introduces decay and noise, mimicking external influences or internal regulatory processes.
+*   **`run_rft_simulation` function**: A wrapper function that sets up initial conditions, runs the simulation, and collects historical data (mean `m_root`, mean `A_modes`, and `event_counts`).
+*   **`fused_mom_update` (CUDA kernel)**: The core update mechanism for state variables (`A`, `Q`, `m_root`). It includes a critical "shredding" mechanism where cells exceeding a `theta` threshold undergo non-linear decay, modeling emergent, non-linear dynamics.
+*   **`fused_mom_update_cpu` (CPU fallback)**: A vectorized PyTorch/NumPy implementation of the `fused_mom_update` logic for CPU execution.
+*   **Gradio Interface**: Provides an intuitive web application to interact with the RFT simulation, adjust parameters, run simulations, and visualize results.
+
+### Why RFT is a Breakthrough
+
+**Novel Approach**: RFT offers a unique departure from traditional simulation methods by focusing on local, distributed interactions within a cellular structure, coupled with dynamic modes and non-linear event triggers. It captures the granularity of individual system components and their complex interplay, leading to emergent behaviors often missed by simpler approaches.
+
+**Shredding Mechanism**: The 'shredding' mechanism (`theta`, `k_shred`) is a core innovation that models sudden, non-linear state transitions or catastrophic events within cells. This is crucial for systems where gradual changes accumulate and lead to abrupt shifts (e.g., market crashes, neural avalanches, material failure).
+
+**Dynamic Feedback Loops**: RFT inherently incorporates dynamic feedback loops, allowing the system's current state to continuously influence its future evolution. This is fundamental for modeling adaptive systems that react to their own internal dynamics and external stimuli.
+
+**Scalability Potential**: Designed for high-performance computing, RFT leverages GPU acceleration via CUDA and CuPy for massive parallel simulations. Its CPU fallback ensures versatility across hardware.
+
+**Versatility**: The abstract nature of RFT's 'cells' and 'modes' makes it incredibly versatile, adaptable to diverse complex systems in finance, biology, engineering, and AI research.
+
+### Example Scenario: Financial Market Cascade
+
+Imagine a financial market where 'cells' represent interconnected financial institutions or assets, and 'modes' represent their internal economic indicators. A high `Xi_norm` (stress indicator) in a cell could trigger 'shredding', simulating a sudden liquidity crisis or a major default. This event then propagates through the network via dynamic feedback, potentially causing other institutions to 'shred' as well, leading to a cascading failure across the entire market. RFT's ability to model these non-linear, emergent cascading events provides invaluable insights for risk management and regulatory stress testing. Experiment with `theta` and `k_shred` to observe how the system responds to different stress tolerances and rates of dissolution!
+
+## 🚀 How to Use the App
+
+1.  **Adjust Parameters**: Use the sliders in the "Simulation Parameters" column to set values for `Ncells` (Number of Cells), `Nmode` (Number of Modes), `Iterations`, `Time Step (dt)`, `Epsilon (eps)`, `Sigma (coupling strength)`, `Theta (Shredding Threshold)`, and `K_shred (Shredding Rate)`. Hover over the parameter names for tooltips with brief explanations.
+2.  **Run Simulation**: Click the "Run Simulation" button. The app will execute the RFT simulation with your chosen parameters.
+3.  **View Results**: The "Simulation Results" column will display:
+    *   A text summary with elapsed time, estimated GFLOPS, final mean values of `m_root` and `A_modes`, and total events in the last iteration.
+    *   Plots showing the historical evolution of mean `m_root`, mean `A_modes`, and cumulative shredding events over iterations.
+
+## 💻 Deployment on Hugging Face Spaces (CPU Basic Instance)
+
+To deploy your own version of this RFT simulation as an interactive Gradio application on Hugging Face Spaces, follow these steps:
+
+1.  **Create a New Hugging Face Space**: Go to `huggingface.co/new-space`.
+2.  **Choose a Repository Name**: Provide a unique and descriptive name for your Space (e.g., `EmergentRFT-Space`).
+3.  **Select `Gradio` as the SDK**: This configures the Space to run your `app.py` with Gradio.
+4.  **Select Hardware Configuration**: For CPU-only deployment, choose a **CPU-enabled instance**. The `CPU Basic` option is sufficient for demonstrating the functionality. Be aware that larger simulations (more cells, modes, or iterations) will be significantly slower on a CPU instance compared to a GPU instance.
+5.  **Set Visibility**: Choose `Public` for easy sharing or `Private` if you prefer restricted access.
+6.  **Click 'Create Space'**.
+7.  **Upload Files**: Upload your `app.py` and `requirements.txt` files to the newly created Space's repository. This can be done via:
+    *   **Hugging Face Interface**: Navigate to the 'Files' tab of your Space, click 'Add file', then 'Upload file', and select both `app.py` and `requirements.txt`.
+    *   **Git Clone**: Clone the Space's Git repository to your local machine, add the `app.py` and `requirements.txt` files to the root directory, and then push the changes back to the Hugging Face repository.
+8.  **Monitor Deployment**: Hugging Face Spaces will automatically detect the `app.py` and `requirements.txt` files. It will then build the environment and launch your Gradio application. You can monitor the build process and check for any errors on the 'Logs' tab of your Space.
+9.  **Access the Application**: Once the deployment is complete (the status indicator turns green), you can access the live interactive RFT simulation interface directly from your Space's main page.
+
+**Note**: For optimal performance and larger-scale simulations, selecting a GPU-enabled instance (e.g., `GPU large/XLarge`) would be highly recommended, provided `cupy-cuda12x` (or relevant CuPy version) is added to `requirements.txt`.
+
+## 🛠️ Files
+
+-   [`app.py`](app.py): The main Gradio application code, including the RFT simulation logic (CUDA kernel and CPU fallback), GFLOPS estimation, plotting, and interface definition.
+-   [`requirements.txt`](requirements.txt): Lists the Python dependencies required for the application.