{"id":28327968,"url":"https://github.com/emanuellcs/entropicrust","last_synced_at":"2025-07-12T20:38:46.180Z","repository":{"id":292974223,"uuid":"982437211","full_name":"emanuellcs/entropicrust","owner":"emanuellcs","description":"Rust-based project exploring chaotic systems through high-performance simulations","archived":false,"fork":false,"pushed_at":"2025-05-13T03:42:43.000Z","size":17,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-04T22:48:51.406Z","etag":null,"topics":["chaos","chaos-theory","chaotic-dynamical-systems","chaotic-systems","mathematics","physics","physics-simulation","rust","rust-lang","rustlang","simulation","visualization"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emanuellcs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-12T22:11:50.000Z","updated_at":"2025-05-14T11:54:56.000Z","dependencies_parsed_at":"2025-05-13T04:35:49.241Z","dependency_job_id":null,"html_url":"https://github.com/emanuellcs/entropicrust","commit_stats":null,"previous_names":["emanuellcs/entropicrust"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/emanuellcs/entropicrust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emanuellcs%2Fentropicrust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emanuellcs%2Fentropicrust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emanuellcs%2Fentropicrust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emanuellcs%2Fentropicrust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emanuellcs","download_url":"https://codeload.github.com/emanuellcs/entropicrust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emanuellcs%2Fentropicrust/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265049748,"owners_count":23703586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chaos","chaos-theory","chaotic-dynamical-systems","chaotic-systems","mathematics","physics","physics-simulation","rust","rust-lang","rustlang","simulation","visualization"],"created_at":"2025-05-26T04:22:29.204Z","updated_at":"2025-07-12T20:38:46.167Z","avatar_url":"https://github.com/emanuellcs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EntropicRust: A Chaotic Systems Visualizer\n\n**Explore the fascinating world of chaos theory with this interactive simulator built in Rust and ggez.**\n\n## Introduction\n\nEntropicRust is a visual simulator for chaotic dynamical systems, implemented in Rust using the [ggez](https://ggez.rs/) game development framework. It enables users to explore and visualize the intricate behavior of several well-known chaotic systems:\n\n*   **Lorenz System**\n*   **Rossler System**\n*   **Aizawa System**\n*   **Chen-Lee System**\n\nBy rendering particle trajectories within an 800x600 window, the simulator illustrates the complex, often fractal-like patterns that emerge from these deterministic yet unpredictable systems. This README provides an overview of chaos theory, the specific systems simulated, the underlying mathematical and physical concepts, and instructions for using the simulator.\n\n## What is Chaos Theory?\n\nChaos theory is the study of complex systems governed by deterministic laws but exhibiting behavior that appears random due to extreme **sensitivity to initial conditions**. This sensitivity, famously known as the **butterfly effect**, means that minuscule changes in the starting state can lead to vastly different outcomes over time.\n\nDespite their deterministic nature (following strict rules), chaotic systems are inherently difficult to predict in the long term.\n\n### Key Characteristics:\n\n*   **Sensitivity to Initial Conditions:** Tiny variations amplify over time, making long-range prediction impossible (e.g., weather forecasting).\n*   **Topological Mixing:** Over time, trajectories from any given region of the system's state space will eventually overlap with any other region, leading to complex mixing.\n*   **Dense Periodic Orbits:** Within the chaotic behavior, there exists an infinite number of unstable periodic patterns (orbits) that the system *could* follow but typically doesn't for long.\n\nChaotic systems often feature **strange attractors** – complex, fractal structures in the system's phase space that trajectories approach over time. These attractors create the visually striking patterns visualized in this simulator.\n\n## History of Chaos Theory\n\nThe seeds of chaos theory were sown in the late 19th century by **Henri Poincaré**. While studying the three-body problem in celestial mechanics, he discovered that the orbits of celestial bodies could be incredibly sensitive to their starting positions and velocities, hinting at the complexity hidden within deterministic systems ([Chaos theory - Wikipedia](https://en.wikipedia.org/wiki/Chaos_theory)).\n\nModern chaos theory truly emerged in the 1960s with the work of meteorologist **Edward Lorenz**. While working with a simplified computer model of atmospheric convection, he accidentally discovered that rounding initial conditions slightly (e.g., from 0.506127 to 0.506) led to drastically different long-term weather predictions. This led to the concept of the butterfly effect and the discovery of the famous **Lorenz attractor**, detailed in his seminal 1963 paper ([Lorenz system - Wikipedia](https://en.wikipedia.org/wiki/Lorenz_system)).\n\nIn the 1970s, scientists like **Otto Rössler** developed simpler systems (like the Rössler attractor) specifically to study chaotic dynamics more easily ([Rössler attractor - Wikipedia](https://en.wikipedia.org/wiki/R%C3%B6ssler_attractor)). The field gained widespread recognition in the 1980s, popularized by James Gleick’s 1987 book, *Chaos: Making a New Science* ([A history of chaos theory - PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3202497/)).\n\nToday, chaos theory is applied across numerous disciplines—physics, biology, economics, engineering, climate science—to understand complex, non-linear phenomena that defy simple prediction.\n\n## Chaotic Systems in This Simulator\n\nThe simulator implements four distinct chaotic systems, each defined by a set of ordinary differential equations (ODEs).\n\n### Lorenz System\n\n*   **Background:** Developed by Edward Lorenz (1963) from a simplified model of atmospheric convection. It's one of the most iconic examples of chaos.\n*   **Equations:**\n    $$\n    \\begin{aligned}\n    \\dot{x} \u0026= \\sigma (y - x) \\\\\n    \\dot{y} \u0026= x (\\rho - z) - y \\\\\n    \\dot{z} \u0026= x y - \\beta z\n    \\end{aligned}\n    $$\n*   **Default Parameters:** $\\sigma = 10.0$ (Prandtl number), $\\rho = 28.0$ (Rayleigh number), $\\beta = 8/3$ (geometric factor).\n*   **Attractor:** Exhibits the famous butterfly-shaped strange attractor with a fractal dimension around 2.06.\n*   **Significance:** Historically crucial for demonstrating deterministic chaos and the butterfly effect in a tangible model related to weather.\n\n### Rossler System\n\n*   **Background:** Studied by Otto Rössler (1970s) as a simpler system exhibiting chaos, inspired by chemical kinetics.\n*   **Equations:**\n    $$\n    \\begin{aligned}\n    \\dot{x} \u0026= -y - z \\\\\n    \\dot{y} \u0026= x + a y \\\\\n    \\dot{z} \u0026= b + z (x - c)\n    \\end{aligned}\n    $$\n*   **Default Parameters:** $a = 0.2$, $b = 0.2$, $c = 5.7$. Parameter `c` often controls the transition to chaos.\n*   **Attractor:** Produces a characteristic spiral-shaped or funnel-like strange attractor.\n*   **Significance:** Its relative simplicity (only one non-linear term) makes it ideal for studying the fundamental properties of chaotic dynamics.\n\n### Aizawa System\n\n*   **Background:** A less common but visually interesting 3D chaotic system known for its complex, often spherical or toroidal attractor structure. Used in studies of chaotic dynamics and sometimes encryption. ([Aizawa Attractor - Algosome](https://www.algosome.com/articles/aizawa-attractor-chaos.html))\n*   **Equations:**\n    $$\n    \\begin{aligned}\n    \\dot{x} \u0026= (z - b) x - d y \\\\\n    \\dot{y} \u0026= d x + (z - b) y \\\\\n    \\dot{z} \u0026= c + a z - \\frac{z^3}{3} - (x^2 + y^2)(1 + e z) + f z x^3\n    \\end{aligned}\n    $$\n*   **Default Parameters:** $a = 0.95$, $b = 0.7$, $c = 0.6$, $d = 3.5$, $e = 0.25$, $f = 0.1$.\n*   **Attractor:** Generates intricate, often multi-folded spherical or tube-like structures.\n*   **Significance:** Demonstrates the diversity of attractor shapes possible in 3D chaotic systems.\n\n### Chen-Lee System\n\n*   **Background:** Derived from the Euler equations for rigid body motion (like a gyroscope) with feedback control, developed around 2004 by Chen and Lee. ([Chen-Lee Attractor - Vorillaz](https://www.vorillaz.com/chen-lee-attractor/))\n*   **Equations:**\n    $$\n    \\begin{aligned}\n    \\dot{x} \u0026= \\alpha x - y z \\\\\n    \\dot{y} \u0026= \\beta y + x z \\\\\n    \\dot{z} \u0026= \\gamma z + \\frac{x y}{3}\n    \\end{aligned}\n    $$\n*   **Default Parameters:** $\\alpha = 5.0$, $\\beta = -10.0$, $\\gamma = -0.38$.\n*   **Attractor:** Can produce complex multi-scroll attractors depending on parameters.\n*   **Significance:** Connects chaos theory directly to physical systems in mechanics and control engineering.\n\n### System Summary Table\n\n| System   | Key Origin / Inspiration | Attractor Shape (Typical) | Default Parameters                                         |\n| :------- | :----------------------- | :------------------------ | :------------------------------------------------------- |\n| Lorenz   | Atmospheric Convection   | Butterfly                 | $\\sigma=10.0, \\rho=28.0, \\beta=8/3$                      |\n| Rossler  | Chemical Kinetics        | Spiral / Funnel           | $a=0.2, b=0.2, c=5.7$                                    |\n| Aizawa   | Mathematical Exploration | Spherical / Toroidal      | $a=0.95, b=0.7, c=0.6, d=3.5, e=0.25, f=0.1$             |\n| Chen-Lee | Rigid Body Motion        | Multi-scroll              | $\\alpha=5.0, \\beta=-10.0, \\gamma=-0.38$                  |\n\n## Mathematical Concepts\n\nEach chaotic system is defined by a set of **Ordinary Differential Equations (ODEs)**. These equations describe how the state variables (typically $x, y, z$) change over time ($\\dot{x} = dx/dt$, etc.).\n\nSince these ODEs often cannot be solved analytically to get an exact formula for the state at any time $t$, we use **numerical methods** to approximate the solution. This simulator employs the **Euler method**, a simple first-order numerical procedure.\n\nThe Euler method updates the state vector $\\mathbf{x} = (x, y, z)$ at discrete time steps $\\Delta t$:\n\n$$\n\\mathbf{x}_{n+1} = \\mathbf{x}_n + \\Delta t \\cdot \\mathbf{f}(\\mathbf{x}_n, t_n)\n$$\n\nWhere:\n*   $\\mathbf{x}_n$ is the state at the current step $n$.\n*   $\\mathbf{x}_{n+1}$ is the approximated state at the next step $n+1$.\n*   $\\Delta t$ is the time step size (influenced by the adjustable time scale in the simulator).\n*   $\\mathbf{f}(\\mathbf{x}_n, t_n)$ is the vector of derivatives ($\\dot{x}, \\dot{y}, \\dot{z}$) calculated using the system's equations at state $\\mathbf{x}_n$.\n\nWhile simple, the Euler method is sufficient for visualizing the *qualitative* behavior and attractor shapes of these systems. More accurate (but computationally intensive) methods like Runge-Kutta exist but are not implemented here.\n\nUsers can interactively adjust the system parameters (e.g., $\\sigma, \\rho, \\beta$ for Lorenz) to observe how the dynamics change, potentially transitioning between stable, periodic, and chaotic regimes.\n\n## Physical Concepts\n\nWhile some chaotic systems are purely mathematical constructs, others have direct physical interpretations:\n\n*   **Lorenz System:** As mentioned, it models simplified atmospheric convection. $x$ relates to convective intensity, $y$ to horizontal temperature difference, and $z$ to vertical temperature difference. It demonstrates how chaotic behavior can arise naturally in fluid dynamics and weather systems.\n*   **Chen-Lee System:** Represents the dynamics of a spinning rigid body (like a gyroscope) subject to certain feedback controls. This links chaos theory to mechanical engineering and control systems.\n*   **Rossler \u0026 Aizawa Systems:** While less directly tied to specific physical scenarios, they model general types of non-linear interactions found in fields like chemical reactions (Rossler) or dissipative systems.\n\nUnderstanding these connections helps appreciate how abstract mathematical chaos manifests in real-world phenomena.\n\n## Visualization and Interpretation\n\nThe simulator visualizes the system dynamics by tracking multiple particles (default 50, adjustable). Each particle's position $(x, y, z)$ evolves according to the selected system's ODEs, solved via the Euler method.\n\n*   **2D Projection:** The 3D state $(x, y, z)$ is projected onto the 2D screen (typically mapping $x$ to the horizontal axis and $y$ or $z$ to the vertical axis, depending on the system view).\n*   **Particle Trails:** Each particle leaves a trail (default 100 points) tracing its recent path. These trails collectively reveal the structure of the system's attractor.\n*   **Interactivity:** Users can manipulate parameters, time scale, and particle count to explore the system's behavior dynamically.\n\nThis visualization helps users intuitively grasp:\n*   The shape and complexity of **strange attractors**.\n*   The **butterfly effect** as initially close particles diverge rapidly.\n*   How **parameter changes** alter the attractor structure and system dynamics (e.g., bifurcations, transitions to chaos).\n\n## Using the Simulator\n\n### Prerequisites\n\n*   **Rust:** Ensure you have Rust installed. You can get it from [rustup.rs](https://rustup.rs/).\n*   **ggez Dependencies:** You might need to install system libraries required by ggez (e.g., `libudev-dev` and `pkg-config` on Debian/Ubuntu, or equivalent). Check the [ggez documentation](https://ggez.rs/docs/) for details.\n\n### Running the Simulator\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/emanuellcs/entropicrust\n    cd entropicrust\n    ```\n2.  **Run using Cargo:**\n    ```bash\n    cargo run --release\n    ```\n    (Using `--release` is recommended for better performance).\n\n### Controls\n\n*   `1` - `4`: Switch system (1: Lorenz, 2: Rossler, 3: Aizawa, 4: Chen-Lee).\n*   `Q`/`A`: Adjust first primary parameter ($\\sigma$/$a$/$a$/$\\alpha$).\n*   `W`/`S`: Adjust second primary parameter ($\\rho$/$b$/$b$/$\\beta$).\n*   `E`/`D`: Adjust third primary parameter ($\\beta$/$c$/$c$/$\\gamma$).\n*   `R`/`F`: Adjust fourth parameter (Aizawa: $d$).\n*   `T`/`G`: Adjust fifth parameter (Aizawa: $e$).\n*   `Y`/`H` (Key H might conflict with Help): Adjust sixth parameter (Aizawa: $f$). *Note: Check actual implementation for Aizawa parameter keys beyond R/F.*\n*   `Z`/`X`: Increase/Decrease time scale (simulation speed).\n*   `C`/`V`: Increase/Decrease number of particles.\n*   `P`: Toggle particle trails On/Off. *(Note: Original README said 'T', check implementation)*\n*   `H`: Toggle help UI overlay showing controls and parameters.\n*   `R` / `Backspace`: Reset particle positions to initial random values.\n*   `Escape`: Quit the simulator.\n\n### Example Usage\n\n1.  Start the simulator (`cargo run --release`). It defaults to the Lorenz system.\n2.  Press `2` to switch to the Rossler system. Observe the spiral attractor.\n3.  Use `E`/`D` to change parameter `c`. Notice how the attractor's shape and complexity change.\n4.  Press `P` to toggle trails off and on.\n5.  Use `Z`/`X` to speed up or slow down the simulation.\n6.  Press `H` to view the current parameter values and controls.\n\n## Future Plans\n\nFuture versions of EntropicRust aim to include:\n\n*   Implementation of more accurate numerical solvers (e.g., Runge-Kutta 4).\n*   Additional chaotic systems.\n*   Improved visualization options (e.g., camera controls, color mapping).\n*   Performance optimizations.\n*   Bug fixes.\n*   Pre-compiled binaries for easier setup on Windows, macOS, and Linux.\n\nStay tuned for updates!\n\n## Conclusion\n\nEntropicRust offers an engaging, interactive platform to explore the captivating beauty and complexity of chaos theory. By visualizing the intricate dances of particles governed by simple deterministic equations, users can gain a deeper intuition for concepts like strange attractors, sensitivity to initial conditions, and the profound ways simple rules can generate seemingly infinite complexity. It serves as both an educational tool and a visual testament to the fascinating nature of non-linear dynamics.\n\n## Citations \u0026 Further Reading\n\n*   [Chaos theory - Wikipedia](https://en.wikipedia.org/wiki/Chaos_theory)\n*   [Lorenz system - Wikipedia](https://en.wikipedia.org/wiki/Lorenz_system)\n*   [Rössler attractor - Wikipedia](https://en.wikipedia.org/wiki/R%C3%B6ssler_attractor)\n*   [Aizawa Attractor - Algosome](https://www.algosome.com/articles/aizawa-attractor-chaos.html) (Example resource)\n*   [Chen-Lee Attractor - Vorillaz](https://www.vorillaz.com/chen-lee-attractor/) (Example resource)\n*   [A history of chaos theory - PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3202497/)\n*   Gleick, James. *Chaos: Making a New Science*. Penguin Books, 1987. (Classic popular science book)\n*   Strogatz, Steven H. *Nonlinear Dynamics and Chaos*. Westview Press, 2nd Edition, 2015. (Standard textbook)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femanuellcs%2Fentropicrust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femanuellcs%2Fentropicrust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femanuellcs%2Fentropicrust/lists"}