rippl 0.1.3__tar.gz

rippl-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeuralWave Core Contributors
+
+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.

rippl-0.1.3/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: rippl
+Version: 0.1.3
+Summary: High-performance physics compiler and PINN engine.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: pydantic
+Provides-Extra: distributed
+Requires-Dist: pytorch-lightning>=2.0; extra == "distributed"
+Dynamic: license-file
+
+# Rippl
+### Differentiable Physics Engine for PyTorch
+
+![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
+![PyPI Version](https://img.shields.io/badge/pypi-v0.0.1-blue)
+![License](https://img.shields.io/badge/license-MIT-orange)
+![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)
+
+---
+
+**Rippl** is a PyTorch-native, C++-less scientific machine learning framework designed for researchers who are tired of bloated dependencies and slow development cycles. It bridges the gap between **Physics-Informed Neural Networks (PINNs)** and **Discrete Numerical Simulation (FDM)** into a unified, Pydantic-validated API.
+
+## Why Rippl? (The Hook)
+
+Most SciML libraries suffer from "Academic Bloat": opaque C++ bindings, fragile custom CUDA kernels, and gradient pathologies that make training feel like alchemy. Rippl cuts through the noise:
+
+- **Strictly Native PyTorch**: No custom C++ or CUDA. We use `F.conv2d` discrete stencils for performance, meaning it runs anywhere PyTorch does—from your MacBook to an H100 cluster.
+- **The $O(1)$ Autograd Cache**: Our `requires_derived` system pre-caches tensors and graph paths. Stop wasting VRAM on redundant graph traversals during complex PDE residual computations.
+- **Algebraic Hard Constraints**: Forget "soft" boundary losses that clash with your physics. Rippl enforces Dirichlet and Neumann conditions algebraically using distance-field masking, ensuring zero-error boundaries from step one.
+- **Differentiable Simulation**: Backprop through time (BPTT) using standard FDM stencils mapped directly to convolution operations.
+
+---
+
+## Installation
+
+```bash
+pip install git+https://github.com/esranow/rippleml.git
+```
+
+*For local development:*
+```bash
+git clone https://github.com/esranow/rippl.git
+cd rippl && pip install -e .
+```
+
+---
+
+## The 10-Line Quickstart
+
+Solve a 1D Wave Equation ($u_{tt} - c^2 u_{xx} = 0$) with zero-gradient overhead:
+
+```python
+import torch
+from rippl.core import System, Domain, Experiment
+from rippl.physics.operators import Laplacian, TimeDerivative
+from rippl.physics.equation import Equation
+
+# 1. Define the Physics (u_tt - 1.0 * u_xx = 0)
+wave_eq = Equation([
+    (1.0, TimeDerivative(order=2)), 
+    (-1.0, Laplacian())
+])
+
+# 2. Setup the System and Domain
+domain = Domain(spatial_dims=1, bounds=[(0, 1)], resolution=(100,))
+system = System(equation=wave_eq, domain=domain, fields=["u"])
+
+# 3. Train the PINN
+model = torch.nn.Sequential(torch.nn.Linear(2, 50), torch.nn.Tanh(), torch.nn.Linear(50, 1))
+exp = Experiment(system, model, torch.optim.Adam(model.parameters()))
+exp.train(epochs=100)
+```
+
+---
+
+## Deep Dive: Core Architecture
+
+### 1. The Autograd Cache (`requires_derived`)
+In standard PINNs, calculating $u_{xxt}$ requires multiple passes through the autograd graph. Rippl's engine analyzes the `Operator` signatures in your `EquationSystem` and builds a directed acyclic graph (DAG) of required derivatives. These are computed in a single optimized pass and cached in the `derived` dictionary, slashing the memory footprint of high-order PDEs.
+
+### 2. Algebraic Boundaries
+Soft boundary losses are the primary cause of PINN instability. Rippl uses a `HardConstraintWrapper` combined with a `DistanceFunction` $D(x)$:
+$$u_{pred}(x) = G(x) \cdot u_{model}(x) + B(x)$$
+Where $G(x)$ vanishes at the boundary and $B(x)$ enforces the exact value. The result? **The optimizer never sees the boundary; it only sees the residual.**
+
+### 3. Differentiable FDM Convolutions
+Standard Finite Difference Methods (FDM) are usually isolated from ML training. Rippl maps these stencils to `torch.nn.functional.conv2d`. This allows you to use a traditional solver as a "Layer" in your network, enabling hybrid architectures that are both numerically stable and learnable.
+
+---
+
+## Advanced Physics Capabilities
+
+- **Spectral Bias Mitigation**: Native support for **SIRENs** (Sinusoidal Representation Networks) and **Fourier Neural Operators (FNOs)** to capture high-frequency shock fronts.
+- **Conservation Law Enforcement**: Wrappers for enforcing flux conservation and divergence-free fields (e.g., in Navier-Stokes).
+- **Inverse Problems**: Parameters (like viscosity $\nu$ or wave speed $c$) can be marked as `requires_grad`, allowing the system to discover physics from raw data automatically.
+
+---
+
+## "Vibecoding" & Contribution Philosophy
+
+Rippl is built for **speed and transparency**. Our codebase is intentionally monolithic and terse. We prioritize architectural elegance over feature-creep.
+
+**The Contract:**
+1. **Strict Perimeter**: All inputs are validated via Pydantic. If your dimensions don't match your physics, Rippl fails fast with a clear error message.
+2. **Raw Core**: Inside the loop, it's pure, unadulterated PyTorch. No abstraction leaks. No hidden overhead.
+
+If you want to contribute, keep it dry. No boilerplate. No unnecessary classes. If it can be done with a tensor operation, do it with a tensor operation.
+
+---
+
+## License
+MIT. Go build something cool.

rippl-0.1.3/README.md

@@ -0,0 +1,102 @@
+# Rippl
+### Differentiable Physics Engine for PyTorch
+
+![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
+![PyPI Version](https://img.shields.io/badge/pypi-v0.0.1-blue)
+![License](https://img.shields.io/badge/license-MIT-orange)
+![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)
+
+---
+
+**Rippl** is a PyTorch-native, C++-less scientific machine learning framework designed for researchers who are tired of bloated dependencies and slow development cycles. It bridges the gap between **Physics-Informed Neural Networks (PINNs)** and **Discrete Numerical Simulation (FDM)** into a unified, Pydantic-validated API.
+
+## Why Rippl? (The Hook)
+
+Most SciML libraries suffer from "Academic Bloat": opaque C++ bindings, fragile custom CUDA kernels, and gradient pathologies that make training feel like alchemy. Rippl cuts through the noise:
+
+- **Strictly Native PyTorch**: No custom C++ or CUDA. We use `F.conv2d` discrete stencils for performance, meaning it runs anywhere PyTorch does—from your MacBook to an H100 cluster.
+- **The $O(1)$ Autograd Cache**: Our `requires_derived` system pre-caches tensors and graph paths. Stop wasting VRAM on redundant graph traversals during complex PDE residual computations.
+- **Algebraic Hard Constraints**: Forget "soft" boundary losses that clash with your physics. Rippl enforces Dirichlet and Neumann conditions algebraically using distance-field masking, ensuring zero-error boundaries from step one.
+- **Differentiable Simulation**: Backprop through time (BPTT) using standard FDM stencils mapped directly to convolution operations.
+
+---
+
+## Installation
+
+```bash
+pip install git+https://github.com/esranow/rippleml.git
+```
+
+*For local development:*
+```bash
+git clone https://github.com/esranow/rippl.git
+cd rippl && pip install -e .
+```
+
+---
+
+## The 10-Line Quickstart
+
+Solve a 1D Wave Equation ($u_{tt} - c^2 u_{xx} = 0$) with zero-gradient overhead:
+
+```python
+import torch
+from rippl.core import System, Domain, Experiment
+from rippl.physics.operators import Laplacian, TimeDerivative
+from rippl.physics.equation import Equation
+
+# 1. Define the Physics (u_tt - 1.0 * u_xx = 0)
+wave_eq = Equation([
+    (1.0, TimeDerivative(order=2)), 
+    (-1.0, Laplacian())
+])
+
+# 2. Setup the System and Domain
+domain = Domain(spatial_dims=1, bounds=[(0, 1)], resolution=(100,))
+system = System(equation=wave_eq, domain=domain, fields=["u"])
+
+# 3. Train the PINN
+model = torch.nn.Sequential(torch.nn.Linear(2, 50), torch.nn.Tanh(), torch.nn.Linear(50, 1))
+exp = Experiment(system, model, torch.optim.Adam(model.parameters()))
+exp.train(epochs=100)
+```
+
+---
+
+## Deep Dive: Core Architecture
+
+### 1. The Autograd Cache (`requires_derived`)
+In standard PINNs, calculating $u_{xxt}$ requires multiple passes through the autograd graph. Rippl's engine analyzes the `Operator` signatures in your `EquationSystem` and builds a directed acyclic graph (DAG) of required derivatives. These are computed in a single optimized pass and cached in the `derived` dictionary, slashing the memory footprint of high-order PDEs.
+
+### 2. Algebraic Boundaries
+Soft boundary losses are the primary cause of PINN instability. Rippl uses a `HardConstraintWrapper` combined with a `DistanceFunction` $D(x)$:
+$$u_{pred}(x) = G(x) \cdot u_{model}(x) + B(x)$$
+Where $G(x)$ vanishes at the boundary and $B(x)$ enforces the exact value. The result? **The optimizer never sees the boundary; it only sees the residual.**
+
+### 3. Differentiable FDM Convolutions
+Standard Finite Difference Methods (FDM) are usually isolated from ML training. Rippl maps these stencils to `torch.nn.functional.conv2d`. This allows you to use a traditional solver as a "Layer" in your network, enabling hybrid architectures that are both numerically stable and learnable.
+
+---
+
+## Advanced Physics Capabilities
+
+- **Spectral Bias Mitigation**: Native support for **SIRENs** (Sinusoidal Representation Networks) and **Fourier Neural Operators (FNOs)** to capture high-frequency shock fronts.
+- **Conservation Law Enforcement**: Wrappers for enforcing flux conservation and divergence-free fields (e.g., in Navier-Stokes).
+- **Inverse Problems**: Parameters (like viscosity $\nu$ or wave speed $c$) can be marked as `requires_grad`, allowing the system to discover physics from raw data automatically.
+
+---
+
+## "Vibecoding" & Contribution Philosophy
+
+Rippl is built for **speed and transparency**. Our codebase is intentionally monolithic and terse. We prioritize architectural elegance over feature-creep.
+
+**The Contract:**
+1. **Strict Perimeter**: All inputs are validated via Pydantic. If your dimensions don't match your physics, Rippl fails fast with a clear error message.
+2. **Raw Core**: Inside the loop, it's pure, unadulterated PyTorch. No abstraction leaks. No hidden overhead.
+
+If you want to contribute, keep it dry. No boilerplate. No unnecessary classes. If it can be done with a tensor operation, do it with a tensor operation.
+
+---
+
+## License
+MIT. Go build something cool.

rippl-0.1.3/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rippl"
+version = "0.1.3"
+description = "High-performance physics compiler and PINN engine."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "torch>=2.0",
+    "pydantic"
+]
+
+[project.optional-dependencies]
+distributed = ["pytorch-lightning>=2.0"]
+
+[project.scripts]
+rippl = "rippl.cli:main"
+
+[tool.setuptools]
+packages = ["rippl", "rippl.core", "rippl.physics", "rippl.solvers", "rippl.training", "rippl.nn", "rippl.config", "rippl.operators", "rippl.io", "rippl.datasets", "rippl.diagnostics"]
+
+[tool.pytest.ini_options]
+testpaths = ["rippl/tests"]
+python_files = "test_*.py"

rippl-0.1.3/rippl/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.0.1"
+# from rippl.api import train, simulate, identify
+from rippl.core.system import System, Domain, Constraint
+from rippl.core.config import register_operator, register_solver
+from rippl.core.api import compile, run
+
+__all__ = ["System", "Domain", "Constraint", "register_operator", "register_solver", "compile", "run"]

rippl-0.1.3/rippl/api.py

@@ -0,0 +1,146 @@
+import torch
+import os
+from typing import Union, Dict, Any, Optional, Tuple
+from rippl.core.config import ConfigParser
+from rippl.core.system import System
+from rippl.core.experiment import Experiment
+from rippl.nn.registry import build_model, load_model
+from rippl.export.exporter import export_model
+
+def train(config_path_or_dict: Union[str, Dict[str, Any]]) -> Tuple[torch.nn.Module, Dict[str, Any]]:
+    """
+    Train a physics-informed neural network model based on the provided configuration.
+
+    Args:
+        config_path_or_dict: Path to a YAML/JSON config file or a configuration dictionary.
+
+    Returns:
+        A tuple of (trained_model, training_results).
+    """
+    config = ConfigParser.load(config_path_or_dict)
+    system = System.from_config(config)
+    
+    # Model configuration
+    model_cfg = config.get("model", {})
+    if not model_cfg:
+        raise ValueError("Configuration missing 'model' section.")
+        
+    model = build_model(model_cfg["name"], model_cfg["config"])
+    
+    # Training configuration
+    train_cfg = config.get("training", {})
+    if not train_cfg:
+        raise ValueError("Configuration missing 'training' section.")
+        
+    optimizer_name = train_cfg.get("optimizer", "Adam")
+    learning_rate = train_cfg.get("lr", 1e-3)
+    optimizer_class = getattr(torch.optim, optimizer_name)
+    optimizer = optimizer_class(model.parameters(), lr=learning_rate)
+    
+    # Experiment orchestration
+    experiment_kwargs = train_cfg.get("experiment_kwargs", {})
+    experiment = Experiment(system, model, optimizer, **experiment_kwargs)
+    
+    # Coordinates for training
+    # Default to a dense grid from the domain if not specified
+    if "data" in config and "coords" in config["data"]:
+        coords = torch.tensor(config["data"]["coords"], dtype=torch.float32)
+    else:
+        coords, _ = system.domain.build_grid()
+        coords = coords.reshape(-1, coords.shape[-1])
+    
+    # Optional logger
+    logger = None
+    if "logging" in config:
+        from rippl.logging.logger import RipplLogger
+        logger = RipplLogger(**config["logging"])
+        
+    results = experiment.train(
+        coords, 
+        epochs=train_cfg.get("epochs", 100),
+        ntk_freq=train_cfg.get("ntk_freq", 500),
+        patience=train_cfg.get("patience", 200),
+        logger=logger
+    )
+    
+    return model, results
+
+def simulate(config_path_or_dict: Union[str, Dict[str, Any]]) -> torch.Tensor:
+    """
+    Run a trained model or a numerical solver for inference.
+
+    Args:
+        config_path_or_dict: Path to a configuration file or a dictionary.
+
+    Returns:
+        A torch.Tensor containing the simulated field values.
+    """
+    config = ConfigParser.load(config_path_or_dict)
+    
+    # If a model path is provided in config, load it.
+    # Otherwise, check if an FD solver is requested.
+    if "model_path" in config:
+        model = load_model(config["model_path"])
+        system = System.from_config(config)
+        coords, _ = system.domain.build_grid()
+        # Flatten and evaluate
+        original_shape = coords.shape[:-1]
+        coords_flat = coords.reshape(-1, coords.shape[-1])
+        with torch.no_grad():
+            output = model(coords_flat)
+        # Reshape back to grid
+        if isinstance(output, dict):
+            return {k: v.view(*original_shape, 1) for k, v in output.items()}
+        return output.view(*original_shape, 1)
+    
+    elif "solver" in config:
+        from rippl.core.config import get_solver_fn
+        solver_name = config["solver"]["name"]
+        solver_fn = get_solver_fn(solver_name)
+        return solver_fn(**config["solver"].get("kwargs", {}))
+        
+    raise ValueError("Simulation requires either 'model_path' or 'solver' in config.")
+
+def identify(config_path_or_dict: Union[str, Dict[str, Any]], data_path: str) -> Dict[str, Any]:
+    """
+    Run parameter discovery (Digital Twin) using sensor data.
+
+    Args:
+        config_path_or_dict: Path to a configuration file or a dictionary.
+        data_path: Path to the sensor data file (e.g., CSV).
+
+    Returns:
+        A dictionary containing identified parameters and their history.
+    """
+    config = ConfigParser.load(config_path_or_dict)
+    system = System.from_config(config)
+    
+    # Load model
+    model_cfg = config["model"]
+    model = build_model(model_cfg["name"], model_cfg["config"])
+    
+    # Digital Twin setup
+    from rippl.core.inverse import DigitalTwin, InverseParameter
+    params_data = config["physics"].get("inverse_parameters", [])
+    parameters = []
+    for p_data in params_data:
+        parameters.append(InverseParameter(**p_data))
+        
+    # Sensor data columns
+    data_cfg = config["data"]
+    dt = DigitalTwin.from_csv(
+        system, model, parameters, 
+        csv_path=data_path,
+        coord_cols=data_cfg["coord_cols"],
+        field_cols=data_cfg["field_cols"],
+        data_weight=data_cfg.get("data_weight", 1.0),
+        physics_weight=data_cfg.get("physics_weight", 1.0)
+    )
+    
+    train_cfg = config.get("training", {})
+    results = dt.train(
+        epochs=train_cfg.get("epochs", 5000),
+        lr=train_cfg.get("lr", 1e-3)
+    )
+    
+    return results

rippl-0.1.3/rippl/cli.py

@@ -0,0 +1,120 @@
+import argparse
+import sys
+import os
+import yaml
+import torch
+from rippl.api import train, simulate
+from rippl.nn.registry import load_model
+from rippl.export.exporter import export_model
+from rippl.core.config import ConfigParser
+
+def main():
+    """
+    Rippl CLI Entrypoint.
+    Provides commands for training, simulation, and model export.
+    """
+    parser = argparse.ArgumentParser(
+        description="Rippl: Modular Physics-ML Framework for Enterprise Wave PDEs",
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Train command
+    train_parser = subparsers.add_parser("train", help="Train a PINN model from a configuration file")
+    train_parser.add_argument("config", help="Path to the YAML or JSON configuration file")
+    train_parser.add_argument("--output", "-o", default="checkpoint", help="Directory to save the trained model")
+
+    # Simulate command
+    sim_parser = subparsers.add_parser("simulate", help="Run inference or a numerical solver")
+    sim_parser.add_argument("config", help="Path to the configuration file")
+
+    # Export command
+    export_parser = subparsers.add_parser("export", help="Export a trained model to TorchScript or ONNX")
+    export_parser.add_argument("config", help="Path to the configuration file used for training")
+    export_parser.add_argument("model_dir", help="Directory containing the weights.pt and config.json")
+    export_parser.add_argument("--format", default="torchscript", choices=["torchscript", "onnx"], 
+                                help="Target export format (default: torchscript)")
+
+    if len(sys.argv) == 1:
+        parser.print_help()
+        sys.exit(0)
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == "train":
+            print(f"[Rippl] Initializing training from {args.config}...")
+            
+            with open(args.config, 'r') as f:
+                raw_cfg = yaml.safe_load(f)
+                
+            from rippl.config.models import DomainConfig, EquationConfig, OperatorConfig
+            
+            # 2. Enforce strict Pydantic validation before PyTorch logic
+            if "domain" in raw_cfg:
+                DomainConfig(**raw_cfg["domain"])
+            if "equation" in raw_cfg:
+                EquationConfig(**raw_cfg["equation"])
+            if "operators" in raw_cfg:
+                for op in raw_cfg["operators"]:
+                    OperatorConfig(**op)
+            
+            # 3 & 4. Handle Neural Network IoC
+            model_cfg = raw_cfg.get("model", {})
+            if "script" in model_cfg and "class_name" in model_cfg:
+                import importlib.util
+                script_path = model_cfg["script"]
+                class_name = model_cfg["class_name"]
+                
+                spec = importlib.util.spec_from_file_location("custom_model", script_path)
+                custom_module = importlib.util.module_from_spec(spec)
+                sys.modules["custom_model"] = custom_module
+                spec.loader.exec_module(custom_module)
+                
+                model_cls = getattr(custom_module, class_name)
+                kwargs = {k: v for k, v in model_cfg.items() if k not in ["script", "class_name", "type"]}
+                net = model_cls(**kwargs)
+            else:
+                import rippl.nn as rnn
+                model_type = model_cfg.get("type", "MLP")
+                model_cls = getattr(rnn, model_type)
+                kwargs = {k: v for k, v in model_cfg.items() if k != "type"}
+                net = model_cls(**kwargs)
+                
+            from rippl.core.engine import Engine
+            engine = Engine(net)
+            
+            # 5. Compile, fit, and save
+            engine.compile()
+            
+            epochs = raw_cfg.get("training", {}).get("epochs", 10)
+            engine.fit(epochs=epochs, **raw_cfg.get("training", {}))
+            
+            engine.validate()
+            
+            engine.save("output.rpx")
+            
+            print(f"[Rippl] Training successful. Model saved to output.rpx")
+
+        elif args.command == "simulate":
+            print(f"[Rippl] Running simulation from {args.config}...")
+            result = simulate(args.config)
+            print(f"[Rippl] Simulation complete. Output tensor shape: {result.shape}")
+
+        elif args.command == "export":
+            print(f"[Rippl] Exporting model from {args.model_dir} to {args.format} format...")
+            model = load_model(args.model_dir)
+            
+            # Load metadata from training config
+            config = ConfigParser.load(args.config)
+            export_model(model, args.model_dir, format=args.format, metadata=config)
+            
+            print(f"[Rippl] Export successful. Artifacts located in {args.model_dir}/")
+
+    except Exception as e:
+        print(f"[Rippl ERROR] {str(e)}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

rippl-0.1.3/rippl/config/models.py

@@ -0,0 +1,35 @@
+import os
+import json
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel
+
+class OperatorConfig(BaseModel):
+    type: str
+    params: Dict[str, Any] = {}
+
+class EquationConfig(BaseModel):
+    operators: List[OperatorConfig] = []
+    params: Dict[str, Any] = {}
+
+class DomainConfig(BaseModel):
+    spatial_dims: int = 1
+    time_dependent: bool = False
+    bounds: List[List[float]] = []
+    resolution: List[int] = []
+
+class NetworkConfig(BaseModel):
+    params: Dict[str, Any] = {}
+
+def generate_json_schemas(out_dir="schemas/"):
+    Path(out_dir).mkdir(parents=True, exist_ok=True)
+    models = {
+        "OperatorConfig": OperatorConfig,
+        "EquationConfig": EquationConfig,
+        "DomainConfig": DomainConfig,
+        "NetworkConfig": NetworkConfig
+    }
+    for name, model in models.items():
+        schema = model.model_json_schema()
+        with open(os.path.join(out_dir, f"{name}.json"), "w") as f:
+            json.dump(schema, f, indent=2)

rippl-0.1.3/rippl/core/__init__.py

@@ -0,0 +1,14 @@
+"""rippl.core — System, Simulation, Experiment."""
+from rippl.core.system import System, Domain, Constraint, NeumannConstraint
+from rippl.core.equation import Equation
+from rippl.core.equation_system import EquationSystem
+from rippl.core.experiment import Experiment
+from rippl.core.inverse import InverseProblem, InverseParameter, DigitalTwin
+from rippl.core.nondim import ReferenceScales, NondimSystem, NondimModelWrapper
+
+__all__ = [
+    "System", "Domain", "Constraint", "NeumannConstraint",
+    "Equation", "EquationSystem",
+    "Experiment", "InverseProblem", "InverseParameter", "DigitalTwin",
+    "ReferenceScales", "NondimSystem", "NondimModelWrapper"
+]

rippl-0.1.3/rippl/core/api.py

@@ -0,0 +1,86 @@
+import torch
+from typing import Any, Dict, Union
+
+def compile(model: torch.nn.Module, backend: str = "inductor", 
+            mode: str = "max-autotune") -> torch.nn.Module:
+    try:
+        return torch.compile(model, backend=backend, mode=mode)
+    except Exception:
+        # Graceful fallback for unsupported platforms (Windows, older CUDA)
+        import warnings
+        warnings.warn(f"torch.compile backend='{backend}' unavailable. Running eager mode.")
+        return model
+
+def run(domain: Any, equation: Any, model: torch.nn.Module,
+        strategy: str = "auto", devices: Union[int, str] = "auto",
+        precision: str = "bf16-mixed", epochs: int = 10000,
+        **kwargs) -> Dict[str, Any]:
+    try:
+        import pytorch_lightning as pl
+        from rippl.training.lightning_engine import LightningEngine
+        return _run_lightning(domain, equation, model, strategy, devices, 
+                       precision, epochs, kwargs)
+    except ImportError:
+        from rippl.training.pinn_recipe import PINNTrainingRecipe
+        return _run_native(domain, equation, model, epochs, kwargs)
+
+def _run_lightning(domain, equation, model, strategy, devices, 
+                   precision, epochs, kwargs):
+    import pytorch_lightning as pl
+    from rippl.training.lightning_engine import LightningEngine
+    from rippl.core.nondim import AutoScaler
+    
+    scaler = AutoScaler.from_domain_equation(domain, equation)
+    engine = LightningEngine(model=model, equation=equation, scaler=scaler,
+                             lr=kwargs.get("lr", 1e-3),
+                             constraint_weight=kwargs.get("constraint_weight", 100.0),
+                             lbfgs_steps=kwargs.get("lbfgs_steps", 500),
+                             causal=kwargs.get("causal", False))
+    trainer = pl.Trainer(max_epochs=epochs, strategy=strategy, devices=devices,
+                         precision=precision, enable_checkpointing=False, logger=False,
+                         callbacks=kwargs.get("callbacks", []))
+    loader = domain.generate_loader(batch_size=kwargs.get("batch_size", 2048))
+    trainer.fit(engine, train_dataloaders=loader)
+    
+    return {"model_state": model.state_dict(), 
+            "scaler_state": scaler.get_state(),
+            "final_loss": engine.final_loss}
+
+def _run_native(domain, equation, model, epochs, kwargs):
+    # Fallback: uses existing PINNTrainingRecipe directly
+    from rippl.training.pinn_recipe import PINNTrainingRecipe
+    from rippl.core.nondim import AutoScaler
+    from rippl.core.system import System
+    import torch
+
+    device = next(model.parameters()).device
+    scaler = AutoScaler.from_domain_equation(domain, equation)
+    loader = domain.generate_loader(batch_size=kwargs.get("batch_size", 2048))
+    
+    def loss_fn():
+        batch = next(iter(loader))[0].to(device)
+        c = batch.requires_grad_(True)
+        scaled = scaler.scale_inputs(c)
+        u = model(scaled)
+        u_phys = scaler.scale_outputs(u)
+        pde_loss = equation.compute_loss({"u": u_phys} if not isinstance(u_phys, dict) else u_phys, c)
+        return pde_loss, pde_loss
+
+    def constraint_loss_fn():
+        return torch.tensor(0.0, device=device, requires_grad=True), {}
+
+    recipe = PINNTrainingRecipe(
+        model=model,
+        loss_fn=loss_fn,
+        constraint_loss_fn=constraint_loss_fn,
+        device=device,
+        phase_b_epochs=epochs,
+        causal=kwargs.get("causal", False)
+    )
+    result = recipe.run()
+    
+    return {
+        "model_state": model.state_dict(),
+        "scaler_state": scaler.get_state(),
+        "final_loss": result.get("phase_c_final_loss", result.get("phase_b_final_loss", 0.0))
+    }