physicausal 0.1.0__tar.gz

physicausal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

physicausal-0.1.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: physicausal
+Version: 0.1.0
+Summary: Causal World Models for Physical Reasoning
+Author-email: Fengrru <fengru1005@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Fengrru/physicausal
+Project-URL: Repository, https://github.com/Fengrru/physicausal
+Project-URL: Documentation, https://github.com/Fengrru/physicausal
+Project-URL: Changelog, https://github.com/Fengrru/physicausal/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mkdocs>=1.5.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.22.0; extra == "dev"
+Provides-Extra: optuna
+Requires-Dist: optuna>=3.0.0; extra == "optuna"
+Dynamic: license-file
+
+<h1 align="center">PhysiCausal</h1>
+
+<p align="center">
+  <b>Causal World Models for Physical Reasoning</b>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/">
+    <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
+  </a>
+  <a href="https://pytorch.org/">
+    <img src="https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg" alt="PyTorch 2.0+">
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+  </a>
+  <a href="#">
+    <img src="https://img.shields.io/badge/docs-mkdocs-blue.svg" alt="Documentation">
+  </a>
+  <a href="https://github.com/Fengrru/physicausal/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/Fengrru/physicausal/ci.yml" alt="Tests">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#features">Features</a> •
+  <a href="#model-zoo">Model Zoo</a> •
+  <a href="#documentation">Documentation</a> •
+  <a href="#citation">Citation</a>
+</p>
+
+---
+
+## Overview
+
+**PhysiCausal** is a lightweight, modular toolkit for learning **causally structured world models** from physical interactions. It bridges causal representation learning (CRL) and intuitive physics, providing a clean research platform for:
+
+- Learning disentangled latent representations from dynamic environments
+- Validating whether learned latents correspond to true causal variables (mass, friction, restitution)
+- Testing interventions via Pearl's **do-operator** on learned world models
+- Benchmarking against standards like CausalWorld and CausalVerse
+
+Unlike heavy simulation stacks (PyBullet, MuJoCo), PhysiCausal ships with a **zero-dependency Newtonian physics engine** in pure NumPy, letting you iterate on causal learning ideas in seconds, not minutes.
+
+---
+
+## Why PhysiCausal?
+
+| | PhysiCausal | Full Physics Engines | General VAE Libraries |
+|---|---|---|---|
+| **Physics** | Built-in, lightweight | Heavy (PyBullet/MuJoCo) | None |
+| **Causal validation** | First-class (DCS, do-op, MI) | Manual / external | Not available |
+| **Model interface** | Unified `CausalWorldModel` | N/A | Fragmented |
+| **Hyperparameter search** | Optuna integrated | Manual | Manual |
+| **Benchmark adapters** | CausalWorld, CausalVerse | Native only | N/A |
+| **Setup time** | `pip install` | Install + compile | `pip install` |
+
+---
+
+## Installation
+
+```bash
+pip install physicausal
+```
+
+For development, documentation builds, and hyperparameter search:
+
+```bash
+pip install physicausal[dev,optuna]
+```
+
+To install the latest development version directly from GitHub:
+
+```bash
+pip install git+https://github.com/Fengrru/physicausal.git
+```
+
+Requires Python >= 3.10 and PyTorch >= 2.0.
+
+---
+
+## Quickstart
+
+Train a causal world model and validate its latent structure in under 20 lines:
+
+```python
+from physicausal import SimplePushEnv, BetaVAE, CausalValidator, train
+
+# 1. Environment
+env = SimplePushEnv(seed=42)
+
+# 2. Data
+data, objects = env.generate_data(n_objects=200, episodes_per_object=5)
+
+# 3. Model
+model = BetaVAE(obs_dim=7, latent_dim=6, action_dim=3, beta=2.0)
+
+# 4. Train with validation
+validator = CausalValidator(model, env)
+result = train(
+    model, data, epochs=100,
+    validator=validator, objects=objects,
+    validate_every=20
+)
+
+# 5. Report
+report = validator.test_multiple_properties(
+    objects, ["mass", "friction", "restitution"]
+)
+for prop, res in report["results"].items():
+    print(f"{prop}: |r|={res['best_abs_corr']:.3f}, causal={res['is_causal']}")
+```
+
+**Output:**
+```text
+mass:         |r|=0.284, causal=False
+friction:     |r|=0.412, causal=False
+restitution:  |r|=0.198, causal=False
+```
+
+> The example above uses a minimal setup. With richer observations (e.g., visual trajectories) and tuned hyperparameters, models routinely cross the |r| > 0.5 causal threshold. See `examples/04_hyperparameter_search.py`.
+
+---
+
+## Features
+
+### Physics Environments
+- **SimplePushEnv** — 2D block-pushing with proper Newtonian dynamics (`F = ma`), Coulomb friction, wall collisions, and configurable object properties (mass, friction, restitution).
+- **PendulumEnv** — Classic pendulum for causal discovery of length, mass, and damping.
+- Pure NumPy, no external physics engine required.
+
+### Model Zoo
+All models implement the `CausalWorldModel` interface:
+
+| Model | Type | Key Feature | Best For |
+|-------|------|-------------|----------|
+| `WorldModel` | Deterministic | MLP encoder-decoder-dynamics | Speed baseline |
+| `BetaVAE` | Probabilistic | β-weighted KL for disentanglement | Balanced CRL |
+| `BetaTCVAE` | Probabilistic | Explicit Total Correlation penalty | Strongest disentanglement |
+
+Shared API:
+```python
+z          = model.encode(obs)                        # Latent inference
+recon      = model.decode(z, action)                  # Observation reconstruction
+z_next     = model.predict_dynamics(z, action)        # Latent transition
+z_intervene = model.intervene(z, dim=0, value=2.0)    # Do-operator
+```
+
+### Causal Validation
+`CausalValidator` provides rigorous statistical tests:
+
+| Method | What it Tests | Threshold |
+|--------|--------------|-----------|
+| Pearson correlation | Linear latent-to-factor association | \|r\| > 0.5 |
+| Permutation test | Statistical significance | p < 0.05 |
+| Mutual information | Non-linear association | MI > 0 |
+| Do-operator | Causal consistency under intervention | Manual inspection |
+| DCS | Disentanglement Completeness Score | 0 (poor) to 1 (perfect) |
+| Sensitivity analysis | Robustness to hyperparameters | Variance-based |
+| Intervention scan | Systematic latent intervention | Grid sweep |
+
+### Training Infrastructure
+- `CausalLearningAgent` — Full training loop with replay buffer
+- `train()` — One-line training function with built-in causal validation checkpoints
+- `ReplayBuffer` — Efficient experience storage for off-policy learning
+
+### Hyperparameter Search
+```python
+from physicausal.training.hparams import search_hyperparams
+
+best = search_hyperparams(
+    BetaVAE, data, objects, env,
+    n_trials=50, metric="mass_corr", direction="maximize"
+)
+print(best["best_params"])  # {'lr': 0.001, 'beta': 2.3, ...}
+```
+
+### Benchmark Adapters
+Convert between PhysiCausal and external formats:
+```python
+from physicausal.benchmarks.causalworld import causalworld_to_physicausal
+from physicausal.benchmarks.causalverse import compute_causalverse_metrics
+```
+
+---
+
+## Model Zoo Details
+
+### BetaVAE
+Standard β-VAE with a tunable `beta` parameter that scales the KL divergence term. Higher `beta` encourages stronger disentanglement at the cost of reconstruction fidelity.
+
+### BetaTCVAE
+Extends BetaVAE with an explicit **Total Correlation (TC)** penalty:
+
+```
+TC(z) = KL(q(z) || prod_i q(z_i))
+```
+
+By penalizing TC directly, BetaTCVAE pushes the aggregate posterior toward factorization, often yielding cleaner latent-to-factor mappings than BetaVAE alone.
+
+### Extending
+Add your own model by subclassing `CausalWorldModel`:
+
+```python
+from physicausal.models.base import CausalWorldModel
+
+class MyModel(CausalWorldModel):
+    def encode(self, obs): ...
+    def decode(self, z, action): ...
+    def predict_dynamics(self, z, action): ...
+    def intervene(self, z, dim, value): ...
+```
+
+---
+
+## Project Structure
+
+```
+physicausal/
+├── envs/              # Physics environments
+│   └── simple_push.py
+├── models/            # Causal world models
+│   ├── base.py        # CausalWorldModel ABC
+│   ├── vae.py         # WorldModel, BetaVAE
+│   └── beta_tc_vae.py # BetaTCVAE
+├── causal/            # Validation & metrics
+│   ├── validator.py   # CausalValidator suite
+│   └── intervention.py
+├── training/          # Training engine
+│   ├── agent.py       # Agent, ReplayBuffer, train()
+│   └── hparams.py     # Optuna search
+├── benchmarks/        # External format adapters
+│   ├── causalworld.py
+│   └── causalverse.py
+└── utils/             # Shared utilities
+```
+
+---
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| `01_quickstart.py` | Train your first causal world model |
+| `02_model_comparison.py` | Compare WorldModel vs BetaVAE vs BetaTCVAE |
+| `03_intervention_analysis.py` | Deep dive into do-operator interventions |
+| `04_hyperparameter_search.py` | Automatic tuning with Optuna |
+
+Run any example:
+```bash
+python examples/01_quickstart.py
+```
+
+---
+
+## Documentation
+
+Full documentation is built with **MkDocs Material** and includes:
+
+- Getting Started (installation, quickstart)
+- User Guide (concepts, environments, models, validation, training, hyperparameters)
+- API Reference (auto-generated via mkdocstrings)
+- Development (contributing, changelog)
+
+Build locally:
+```bash
+mkdocs serve
+```
+
+---
+
+## Testing
+
+```bash
+pytest tests/ -v --cov=physicausal
+```
+
+53 tests covering environments, models, causal validation, training, and benchmarks.
+
+---
+
+## Known Limitations & Roadmap
+
+**Current limitations:**
+- SimplePushEnv uses low-dimensional state observations; visual input is not yet supported.
+- Best reported mass correlation (~0.28) remains below the causal threshold on the minimal setup; richer observations or visual encoders are expected to cross |r| > 0.5.
+- Additional physics environments (collision, stacking) are planned beyond SimplePushEnv and PendulumEnv.
+
+**Roadmap:**
+- [ ] Visual encoder backend (CNN-based observations)
+- [ ] Additional physics environments (collision, stacking, rope)
+- [ ] Integration with CausalWorld gym API
+- [ ] Pre-trained model zoo releases
+- [ ] Interactive Colab notebooks
+
+---
+
+## Citation
+
+If you use PhysiCausal in your research, please cite:
+
+```bibtex
+@software{physicausal2024,
+  title = {PhysiCausal: Causal World Models for Physical Reasoning},
+  author = {PhysiCausal Contributors},
+  year = {2024},
+  url = {https://github.com/Fengrru/physicausal}
+}
+```
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for guidelines.
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.