How snktshrma272/phiflow works
Project Type and Purpose
• ΦFlow is an open-source, full-stack Python library that provides end-to-end differentiable simulations of PDEs (primarily fluid dynamics) for machine learning and optimization workflows.
• It wraps core physics & geometry abstractions in a backend-agnostic API and plugs into NumPy, Jax, TensorFlow or PyTorch for computation and automatic differentiation.
• It also ships optional visualization layers (console, Matplotlib, Dash web UI), demos, examples, docs and CI pipelines for testing and deployment.
High-Level File Structure & Architectural Patterns
• Top-Level Directories
– phi/ ← Core Python package
– PhiML/ ← Submodule providing typed-dimension tensor abstractions
– demos/, examples/ ← Usage scripts & Jupyter notebooks grouped by domain (grids, mesh, particles, optim)
– docs/ ← Tutorials, API docs, specification, troubleshooting
– tests/ ← Unit tests (commit vs. release), CI scripts in .github/workflows
– setup.py, setup.cfg ← Packaging, dependencies, entry points
• Core Package Layout (phi/)
– field/ ← Field abstractions: grids, masks, resampling, I/O
– geom/ ← Geometric primitives and signed distance fields
– physics/ ← PDE operators: advect, diffuse, sph, fluid solvers
– math/ ← Backend-agnostic math utilities, extrapolation, backends switch
– flow.py ← High-level simulation flows orchestration
– {jax, tf, torch}/
• flow.py ← Bindings of flow.py to Jax/TensorFlow/PyTorch compute graphs
• nets.py ← Neural network layers and integration points
– vis/ ← Visualization layers:
• _console ← Terminal UI (text/ASCII plots)
• _matplotlib← Static plotting
• _dash ← Interactive web UI (Dash + Plotly)
• Architectural Patterns
– Plugin architecture for backends: a single core API delegates compute to the active backend module (NumPy, Jax, TF or PyTorch).
– Layered separation of concerns:
• Core abstractions (fields, geometry, physics)
• Backend adapters (compute + autodiff)
• Visualization adapters
– Object-oriented, vectorized design enabling dimensional agnosticism and reuse.
– CI/CD via GitHub Actions, coverage reports, and submodule management.
Key Components & Interactions
a. Core API Layer (phi)
– Field Manager, Geometry Engine, Physics Solvers, Flow Orchestrator
b. Backend Adapter Layer
– NumPy (default), Jax Adapter, TensorFlow Adapter, PyTorch Adapter
– Each adapter exposes: tensor operations, autodiff, GPU acceleration
c. Visualization Layer
– Console UI ←→ Core (polls simulation state)
– Matplotlib ←→ Core (snapshot plots)
– Dash Web UI ←→ Core (real-time interactive controls & plots)
d. Submodule & External Dependencies
– ΦML for typed tensors
– Third-party libraries: NumPy, Jax, TensorFlow, PyTorch, Dash, Plotly, Matplotlib
– CI: GitHub Actions, coverage, publishing to PyPI
e. User Code & Examples
– demos/ and examples/ import the Core API and optionally choose a backend and visualization
– README and docs drive installation & usage
Data/Control Flow
1. User script or notebook calls phi.Flow simulation API
2. Core orchestrator composes Field + Geometry + Physics operations
3. Computation is dispatched to the selected backend module
4. Resulting state is returned to user or streamed to visualization adapters
5. Visualization layer pulls data via callbacks or direct API calls
6. CI pipelines run tests, coverage, update docs
Detailed Elements
• Clear component names (phi.field, phi.geom, phi.physics, phi.flow, phi.jax.flow, etc.)
• Backend selection mechanism in core (e.g., backend backend.py)
• Visual distinction between synchronous (console/matplotlib) vs. asynchronous (Dash) visualization
• Escape hatch to CUDA custom ops compilation (Installation instructions)
• Test harness and CI workflows as side-bar demonstrating quality gate