Virtual_Pet: Sensing-to-Action Cycle under Thermodynamic Constraints (SATC)

Virtual_Pet (v0.2) is an interactive, light-themed desktop simulation that models a hybrid cognitive-thermodynamic dynamical system. Written entirely in Python with Tkinter, the software transitions away from basic toy loops to formalize a five-species virtual ecosystem regulated by the strict mathematical principles of the SATC Framework.

---

🔬 System Overview & Core Features

Virtual_Pet models the continuous homeostatic and physical states of an agent over infinite iterations, balancing cognitive decay against metabolic expenditure.

• Light-Mode, Retro-Compatible Design: Features an clean, aesthetic off-white dashboard with an LCD green simulation canvas. Dark frames and terminal-black screens are removed in favor of a modern scientific interface.
• Five Distinct Species Profiles: Adopt an Axolotl, Rabbit, Snake, Chlamydosaurus (Frilled Lizard), or Fish. Each features a hand-crafted pixel art matrix, custom eye boundary coordinates for blinking/sleeping, and unique dietary preferences.
• Species-Specific Independent Saving: The dashboard detects active localized save slots (save_axolotl.json, save_rabbit.json, etc.) on boot, allowing you to resume existing sessions.
• Auto-Save & Permadeath (Cease Loop): Progress auto-saves every 5 seconds. If a pet crosses a critical viability boundary (starvation or toxicosis), the save file is instantly wiped from disk and the simulation is permanently halted, requiring a fresh adoption.
• Real-time Z-Space Telemetry: Live feedback displays of both physical coordinates ($x$) and virtual coordinate transformations ($g$) on the right sidebar monitor.

---

🎮 Interface & Interactive Controls

• FEED: Replenishes Satiety ($x_s$) and raises Somatic Toxicity ($x_b$). Spawns species-specific pixel food (a leafy green lettuce for the Rabbit, traditional kibble pellets for others).
• PLAY: Burns Satiety to act on Boredom potentials. Restricted if the pet lacks sufficient energy.
• SLEEP: Restricts active behaviors, closes the eyes of the sprite, and scales base metabolic consumption down to 40%.
• CLEAN: Sweeps away visual physical waste piles on the canvas and clears Somatic Toxicity ($x_b$).
• AUTO-VAC: A toggleable automatic cleaning system. While active, it continuously sweeps toxins at the expense of an added energy dissipation tax.

---

🚀 Execution

Ensure you are running Python 3.8+ with Tkinter compiled on your system.

# Clone the repository
git clone https://github.com/yourusername/virtual_pet.git
cd virtual_pet

# Run the simulation
python virtual_pet.py

---

📐 Mathematical Foundations of the SATC Framework

The metabolic engine under the hood does not use simple timers. It is formulated as a hybrid cognitive-thermodynamic dynamical system using differential geometry, non-linear feedback linearization, and numerical exponential integration.

1. The Hybrid Thermodynamic-Cognitive Agent

An agent $\mathcal{A}$ is formalized as a 6-tuple: $$\mathcal{A} = \left( \mathcal{X}, \mathcal{K}, \mathcal{Z}, \mathcal{M}, \mathbf{f}, \mathcal{P}_{\mathcal{K}} \right)$$

where:

• $\mathcal{X} \subset \mathbb{R}^{4+L}$ is the continuous physical-cognitive state space, where any state is represented as $\mathbf{X} = [x_s, x_c, \mathbf{w}_p, x_e, x_b]^T$.
• $\mathcal{K} \subset \mathcal{X}$ is a closed, convex set representing the viability envelope (the homeostatic bounds).
• $\mathcal{Z} \subset \mathbb{R}^{4+L}$ is the globally linearized virtual state space, represented as $\mathbf{Z} = [g_s, g_c, \mathbf{w}_p, g_e, g_b]^T$.
• $\mathcal{M}: \mathcal{K} \to \mathcal{Z}$ is a bijective, diffeomorphic coordinate transformation mapping (the Homeostatic Map).
• $\mathbf{f}: \mathcal{K} \to \mathbb{R}^{4+L}$ is the non-linear vector field dictating unconstrained system dynamics.
• $\mathcal{P}_{\mathcal{K}}$ is the Projected Dynamical Systems boundary operator preserving physical realism along the boundaries of $\mathcal{K}$.

2. Phase 1: Sensing & The Thermodynamic Ceiling Mapping (The Homeostatic Map)

The agent senses its physical state $\mathbf{X}(t) \in \mathcal{K}$ and projects it into the linearized virtual space $\mathbf{Z}(t) \in \mathcal{Z}$ via $\mathcal{M}$.

For any physiological variable $x_i(t)$ (such as Satiety $x_s$, Conservation/Vitality $x_c$, Active Energy $x_e$, and Somatic Waste $x_b$), the Thermodynamic Ceiling $x_{i,\text{target}}$ is formalized as an asymptotic barrier function $\phi: [0, x_{i,\text{target}}) \to [0, \infty)$: $$g_i = \phi(x_i) = \frac{x_i}{x_{i,\text{target}} - x_i}$$

This mapping guarantees that coordinates approaching their targets asymptotically approach infinity, while coordinates collapsing to zero approach zero. The physical coordinate is recovered via the analytical inverse $\phi^{-1}(g_i)$: $$x_i = \phi^{-1}(g_i) = x_{i,\text{target}}\left(\frac{g_i}{1.0 + g_i}\right)$$

3. Phase 2: Cognitive Coordination

The decision variables $\mathbf{w}_p \in \mathbb{R}^L$ (where $L=4$ represents the channel urges: Hunger, Boredom, Fatigue, and Waste) evolve on a slow time-scale relative to physical decay, governed by: $$\dot{\mathbf{w}}p = \mathbf{f}{w_p}(\mathbf{X}(t))$$

The raw activation $\tilde{\psi}a$ of each cognitive channel $a \in {1, \dots, L}$ is coordinated through a logistic sensor gate $\sigma: \mathbb{R} \to (0, 1)$: $$\tilde{\psi}a = \sigma(\gamma{\text{gate}} w{p,a}) = \left(1 + e^{-\gamma_{\text{gate}} w_{p,a}}\right)^{-1}$$

4. Phase 3: Action Selection (The Selector)

The action selector $\mathcal{S}: \mathbb{R}^L \to [0, 1]^L$ maps raw cognitive potentials to a normalized, competitive behavior vector $\boldsymbol{\psi} = [\psi_1, \dots, \psi_L]^T$ via a smooth lateral inhibition operator: $$\psi_a = \mathcal{S}a(\mathbf{w}p) = g{\alpha{\text{soft}}}\left( \tilde{\psi}a - \sum{b \neq a} \tilde{\psi}_b \right)$$

where $g_{\alpha_{\text{soft}}}(u) = \frac{1}{\alpha_{\text{soft}}}\ln(1 + e^{\alpha_{\text{soft}} u})$ acts as a smooth, differentiable rectifier ($\text{C}^{\infty}$ approximation of ReLU).

5. Phase 4: Energetic Feedback Linearization & Pressure Amplification

The active dissipation cost $C_{\text{active}}$ represents metabolic tax (work, computation, self-catabolism, and Auto-Vac consumption). By applying Exact Feedback Linearization under the mapping $\phi(x_e)$, the metabolic pressure feedback in the linearized space $\mathcal{Z}$ is formalized as: $$\dot{g}_e = \lambda_e g_e - C_g$$

where the virtual metabolic pressure $C_g$ is amplified by a non-linear gain factor: $$C_g = \left[\frac{(1.0 + g_e)^2}{x_{e,\text{target}}}\right] C_{\text{active}}$$

As energy depletes ($x_e \to 0 \implies g_e \to 0$), the virtual metabolic pressure feedback to the cognitive coordinator is exponentially amplified, forcing survival-oriented attractors.

6. Phase 5: Analytical Exponential Integration (Bypassing Stiffness)

To advance the SATC cycle over an integration step $\Delta t$, the biochemical and metabolic dynamics are resolved via exact exponential integration to bypass numerical stiffness: $$g_e(t+\Delta t) = g_e(t)e^{\lambda_e\Delta t} - \left(e^{\lambda_e\Delta t} - 1\right)\lambda_e^{-1} C_g$$

Physical coordinates are then reconstructed and mapped back onto the tangent cone of $\mathcal{K}$ using the analytical inverse: $$\mathbf{X}(t+\Delta t) = \mathcal{P}_{\mathcal{K}}\left( \mathcal{M}^{-1}(\mathbf{Z}(t+\Delta t)) \right)$$