pinnrl 0.1.0__tar.gz

pinnrl-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+pinn/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+.DS_Store
+.ruff_cache
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Training artifacts
+experiments/
+checkpoints/
+*.log
+
+# Model weights
+*.pth
+*.pt
+
+# Notebooks
+notebooks/images/
+.ipynb_checkpoints/
+
+# Docs
+site/
+docs/LINKEDIN.md
+
+# Sensitive
+.env

pinnrl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jose Garcia
+
+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.

pinnrl-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: pinnrl
+Version: 0.1.0
+Summary: Physics-Informed Neural Networks with RL-based adaptive sampling for solving PDEs
+Project-URL: Homepage, https://github.com/josegarciav/PINNs-RL-PDE
+Project-URL: Documentation, https://github.com/josegarciav/PINNs-RL-PDE/tree/main/docs
+Project-URL: Repository, https://github.com/josegarciav/PINNs-RL-PDE
+Project-URL: Issues, https://github.com/josegarciav/PINNs-RL-PDE/issues
+Project-URL: Changelog, https://github.com/josegarciav/PINNs-RL-PDE/blob/main/CHANGELOG.md
+Author-email: Jose Garcia <jgarciaventura23@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: PDE,PINNs,deep learning,partial differential equations,physics-informed neural networks,reinforcement learning,scientific machine learning,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: gymnasium>=0.29.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.15.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: tqdm>=4.65.0
+Provides-Extra: all
+Requires-Dist: black>=23.0.0; extra == 'all'
+Requires-Dist: dash-bootstrap-components>=1.5.0; extra == 'all'
+Requires-Dist: dash>=3.0.0; extra == 'all'
+Requires-Dist: ipywidgets>=8.0.0; extra == 'all'
+Requires-Dist: jupyter>=1.0.0; extra == 'all'
+Requires-Dist: mkdocs-material>=9.4.0; extra == 'all'
+Requires-Dist: mkdocs>=1.5.0; extra == 'all'
+Requires-Dist: mkdocstrings[python]>=0.23.0; extra == 'all'
+Requires-Dist: mypy>=1.5.0; extra == 'all'
+Requires-Dist: nbformat>=5.9.0; extra == 'all'
+Requires-Dist: pre-commit>=3.4.0; extra == 'all'
+Requires-Dist: pydocstyle>=6.3.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
+Requires-Dist: pytest>=7.4.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: scikit-image>=0.21.0; extra == 'all'
+Requires-Dist: seaborn>=0.12.0; extra == 'all'
+Requires-Dist: twine>=5.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.4.0; extra == 'dev'
+Requires-Dist: pydocstyle>=6.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.4.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.23.0; extra == 'docs'
+Provides-Extra: notebooks
+Requires-Dist: ipywidgets>=8.0.0; extra == 'notebooks'
+Requires-Dist: jupyter>=1.0.0; extra == 'notebooks'
+Requires-Dist: nbformat>=5.9.0; extra == 'notebooks'
+Provides-Extra: viz
+Requires-Dist: dash-bootstrap-components>=1.5.0; extra == 'viz'
+Requires-Dist: dash>=3.0.0; extra == 'viz'
+Requires-Dist: scikit-image>=0.21.0; extra == 'viz'
+Requires-Dist: seaborn>=0.12.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/pinnrl-logo.png" alt="pinnrl" width="420"/>
+</p>
+
+# pinnrl &mdash; PINNs + RL for PDEs
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-lightgrey)](https://github.com/josegarciav/PINNs-RL-PDE)
+[![Build](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/josegarciav/PINNs-RL-PDE)
+
+**Solve PDEs with neural networks that learn where to look.**
+
+`pinnrl` combines Physics-Informed Neural Networks (PINNs) with Deep Q-Network reinforcement learning to place collocation points adaptively — concentrating compute where the residual is highest, not where a grid happens to land. Integrate your chosen architecture, your custom equations, a Dashboard trainer, and add exact/quasi-exact analytical solutions for validation.
+
+---
+
+## Why pinnrl?
+
+Traditional PDE solvers (FEM, FDM) require meshes that become expensive in high dimensions or on irregular geometries. PINNs offer a mesh-free alternative, but their accuracy depends critically on *where* training points are sampled. Random or uniform sampling wastes capacity on easy regions while undersampling shocks, steep gradients, and phase boundaries.
+
+`pinnrl` treats collocation point placement as a sequential decision problem. A DQN agent observes the current residual field and selects sampling regions to maximize physics compliance. The result is faster convergence and better accuracy on problems that defeat uniform sampling — Burgers shocks, KdV solitons, Cahn-Hilliard interfaces.
+
+**Real use cases this targets:**
+
+- **Fluid dynamics** — advection-dominated flows, shock formation (Burgers, Convection)
+- **Materials science** — phase-field modeling, spinodal decomposition (Allen-Cahn, Cahn-Hilliard)
+- **Quantitative finance** — option pricing on non-standard payoffs (Black-Scholes)
+- **Nonlinear wave propagation** — soliton dynamics (KdV), resonance (Wave, Pendulum)
+
+---
+
+## Supported PDEs
+
+| PDE | Domain | Key Parameters | Recommended Architecture |
+|-----|--------|----------------|--------------------------|
+| Heat | `[0,1] x [0,T]` | thermal diffusivity `alpha` | Fourier Features |
+| Wave | `[0,1] x [0,T]` | wave speed `c` | SIREN |
+| Burgers | `[-1,1] x [0,T]` | viscosity `nu` | Fourier Features |
+| KdV | `[-pi,pi] x [0,T]` | dispersion `delta` | ResNet |
+| Convection | `[0,1] x [0,T]` | advection velocity `beta` | Fourier Features |
+| Allen-Cahn | `[-1,1] x [0,T]` | interface width `epsilon` | ResNet |
+| Cahn-Hilliard | `[0,1]^2 x [0,T]` | mobility `M`, interface `epsilon` | Self-Attention |
+| Black-Scholes | `[S_min,S_max] x [0,T]` | volatility `sigma`, rate `r` | FeedForward |
+| Pendulum | `[0,2pi] x [0,T]` | damping `gamma`, forcing `F` | SIREN |
+
+---
+
+## Supported Architectures
+
+| Architecture | Best For | Key Hyperparameters |
+|---|---|---|
+| `feedforward` | Smooth, low-frequency solutions | `hidden_dim`, `num_layers`, `activation` |
+| `resnet` | Deep networks, stiff equations | `num_blocks`, `hidden_dim` |
+| `siren` | Oscillatory, wave-type problems | `omega_0` (frequency scale) |
+| `fourier` | High-frequency, spectral accuracy | `mapping_size`, `scale` |
+| `fno` | Operator learning, multi-scale PDEs | `modes` (frequency cutoff), `num_blocks` |
+| `attention` | Multi-scale, complex geometry | `num_heads`, `num_blocks` |
+| `autoencoder` | Latent-space compression tasks | `latent_dim`, `hidden_dim` |
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# Recommended (uv)
+uv add pinnrl
+
+# pip
+pip install pinnrl
+```
+
+Available PDE keys: `heat`, `wave`, `burgers`, `kdv`, `convection`, `allen_cahn`, `cahn_hilliard`, `black_scholes`, `pendulum`.
+
+### Python API — solving the heat equation
+
+```python
+import torch
+from pinnrl.config import Config, ModelConfig, TrainingConfig, EarlyStoppingConfig
+from pinnrl.neural_networks import PINNModel
+from pinnrl.pdes.heat_equation import HeatEquation
+from pinnrl.pdes.pde_base import PDEConfig
+from pinnrl.training.trainer import PDETrainer
+
+device = torch.device("cpu")
+
+training = TrainingConfig(
+    num_epochs=3000, batch_size=2048,
+    num_collocation_points=5000, num_boundary_points=500, num_initial_points=500,
+    learning_rate=1e-3, weight_decay=1e-4, gradient_clipping=1.0,
+    early_stopping=EarlyStoppingConfig(enabled=True, patience=100, min_delta=1e-7),
+    learning_rate_scheduler=None,
+)
+pde_config = PDEConfig(
+    name="heat", domain=[[0.0, 1.0]], time_domain=[0.0, 1.0],
+    parameters={"alpha": 0.01},
+    boundary_conditions={"type": "dirichlet"},
+    initial_condition={"type": "sine", "amplitude": 1.0, "frequency": 2.0},
+    exact_solution={"type": "sin_exp_decay", "amplitude": 1.0, "frequency": 2.0},
+    dimension=1, device=device, training=training,
+)
+config = Config.__new__(Config)
+config.device = device
+config.model = ModelConfig(input_dim=2, hidden_dim=128, output_dim=1,
+                           num_layers=4, activation="tanh", architecture="fourier")
+config.training = training
+config.pde_config = pde_config
+
+pde     = HeatEquation(config=pde_config)
+model   = PINNModel(config=config, device=device)
+trainer = PDETrainer(model=model, pde=pde,
+                     optimizer_config={"learning_rate": 1e-3, "weight_decay": 1e-4},
+                     config=config, device=device)
+trainer.train(num_epochs=3000)
+
+# Validate against exact solution u(x,t) = A * exp(-alpha*(2pi*f/L)^2 * t) * sin(2pi*f*x/L)
+metrics = pde.validate(model, num_points=5000)
+print(f"L2 error: {metrics['l2_error']:.2e}  |  Max error: {metrics['max_error']:.2e}")
+```
+
+
+---
+
+## Features
+
+- **RL-adaptive collocation** — a DQN agent (`src/rl/rl_agent.py`) observes the current residual field and steers point sampling toward high-error regions, reducing wasted forward passes on low-residual areas.
+- **Seven neural architectures** — FeedForward, ResNet, SIREN (periodic activations), Fourier Features (random Fourier mapping), Fourier Neural Operator (spectral convolutions), Self-Attention Transformer, and Autoencoder, all exposed through a single `PINNModel` factory class.
+- **Nine PDEs** — linear to nonlinear, parabolic to hyperbolic, 1D to 2D, spanning thermal diffusion, soliton dynamics, phase-field models, and financial derivatives.
+- **Exact analytical solutions** — every PDE ships with an `exact_solution` method for L2 and max-error validation during and after training; no external reference solver is required.
+- **Adaptive loss weighting** — residual-balancing weights (RBW) and learning-rate-based weights (LRW) automatically re-balance physics, boundary, and initial condition loss terms.
+- **Dash dashboard** — configure and launch experiments, monitor convergence metrics, and compare runs without writing plotting code.
+- **Hardware-aware** — automatically selects CUDA, Apple MPS, or CPU; configurable via the `--device` flag or `config.yaml`.
+
+---
+
+## Comparison with Related Libraries
+
+| Feature | pinnrl | DeepXDE | NeuralPDE.jl |
+|---|---|---|---|
+| RL-based adaptive sampling | Yes | No | No |
+| Architectures bundled | 7 | 3 | 2 |
+| Dashboard trainer | Yes | No | No |
+| Exact solutions built in | Yes | Partial | Partial |
+| Language | Python | Python | Julia |
+| Install | `pip install pinnrl` | `pip install deepxde` | Julia pkg manager |
+
+---
+
+## Roadmap
+
+| Version | Status | Milestones |
+|---|---|---|
+| v0.1 | Now | 9 PDEs, 7 architectures, DQN adaptive sampling, Dash dashboard, exact-solution validation |
+| v0.2 | Planned | PyPI release, 2D/3D geometry, PPO agent option, YAML config schema validation |
+| v0.3 | Planned | Operator learning (DeepONet-style), uncertainty quantification, JAX backend |
+| v1.0 | Future | Stable public API, community PDE registry, full documentation site |
+
+---
+
+## Who Is It For?
+
+- **PhD students and researchers** prototyping mesh-free PDE solvers without implementing adaptive sampling from scratch.
+- **Computational scientists** in fluid dynamics, materials science, or plasma physics benchmarking PINNs against FDM/FEM on standard problems.
+- **Quantitative analysts** exploring neural PDE solvers for high-dimensional option pricing beyond Black-Scholes closed forms.
+- **ML engineers** studying how RL exploration strategies transfer to scientific computing.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue before submitting a large pull request.
+
+**Core development:** Jose Garcia Ventura ([@josegarciav](https://github.com/josegarciav))
+
+**Community contributions** in scope: new PDEs, new architectures, bug fixes, documentation improvements, and example notebooks. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+---
+
+## Citation
+
+If you use `pinnrl` in published work, please cite:
+
+```bibtex
+@software{garcia2024pinnrl,
+  author    = {Garcia Ventura, Jose},
+  title     = {pinnrl: Physics-Informed Neural Networks with Reinforcement Learning Adaptive Sampling},
+  year      = {2024},
+  url       = {https://github.com/josegarciav/PINNs-RL-PDE},
+  note      = {Open-source Python library for mesh-free PDE solving}
+}
+```
+
+---
+
+## License
+
+[MIT License](LICENSE) &copy; 2024 Jose Garcia Ventura

pinnrl-0.1.0/README.md

@@ -0,0 +1,199 @@
+<p align="center">
+  <img src="docs/assets/pinnrl-logo.png" alt="pinnrl" width="420"/>
+</p>
+
+# pinnrl &mdash; PINNs + RL for PDEs
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-lightgrey)](https://github.com/josegarciav/PINNs-RL-PDE)
+[![Build](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/josegarciav/PINNs-RL-PDE)
+
+**Solve PDEs with neural networks that learn where to look.**
+
+`pinnrl` combines Physics-Informed Neural Networks (PINNs) with Deep Q-Network reinforcement learning to place collocation points adaptively — concentrating compute where the residual is highest, not where a grid happens to land. Integrate your chosen architecture, your custom equations, a Dashboard trainer, and add exact/quasi-exact analytical solutions for validation.
+
+---
+
+## Why pinnrl?
+
+Traditional PDE solvers (FEM, FDM) require meshes that become expensive in high dimensions or on irregular geometries. PINNs offer a mesh-free alternative, but their accuracy depends critically on *where* training points are sampled. Random or uniform sampling wastes capacity on easy regions while undersampling shocks, steep gradients, and phase boundaries.
+
+`pinnrl` treats collocation point placement as a sequential decision problem. A DQN agent observes the current residual field and selects sampling regions to maximize physics compliance. The result is faster convergence and better accuracy on problems that defeat uniform sampling — Burgers shocks, KdV solitons, Cahn-Hilliard interfaces.
+
+**Real use cases this targets:**
+
+- **Fluid dynamics** — advection-dominated flows, shock formation (Burgers, Convection)
+- **Materials science** — phase-field modeling, spinodal decomposition (Allen-Cahn, Cahn-Hilliard)
+- **Quantitative finance** — option pricing on non-standard payoffs (Black-Scholes)
+- **Nonlinear wave propagation** — soliton dynamics (KdV), resonance (Wave, Pendulum)
+
+---
+
+## Supported PDEs
+
+| PDE | Domain | Key Parameters | Recommended Architecture |
+|-----|--------|----------------|--------------------------|
+| Heat | `[0,1] x [0,T]` | thermal diffusivity `alpha` | Fourier Features |
+| Wave | `[0,1] x [0,T]` | wave speed `c` | SIREN |
+| Burgers | `[-1,1] x [0,T]` | viscosity `nu` | Fourier Features |
+| KdV | `[-pi,pi] x [0,T]` | dispersion `delta` | ResNet |
+| Convection | `[0,1] x [0,T]` | advection velocity `beta` | Fourier Features |
+| Allen-Cahn | `[-1,1] x [0,T]` | interface width `epsilon` | ResNet |
+| Cahn-Hilliard | `[0,1]^2 x [0,T]` | mobility `M`, interface `epsilon` | Self-Attention |
+| Black-Scholes | `[S_min,S_max] x [0,T]` | volatility `sigma`, rate `r` | FeedForward |
+| Pendulum | `[0,2pi] x [0,T]` | damping `gamma`, forcing `F` | SIREN |
+
+---
+
+## Supported Architectures
+
+| Architecture | Best For | Key Hyperparameters |
+|---|---|---|
+| `feedforward` | Smooth, low-frequency solutions | `hidden_dim`, `num_layers`, `activation` |
+| `resnet` | Deep networks, stiff equations | `num_blocks`, `hidden_dim` |
+| `siren` | Oscillatory, wave-type problems | `omega_0` (frequency scale) |
+| `fourier` | High-frequency, spectral accuracy | `mapping_size`, `scale` |
+| `fno` | Operator learning, multi-scale PDEs | `modes` (frequency cutoff), `num_blocks` |
+| `attention` | Multi-scale, complex geometry | `num_heads`, `num_blocks` |
+| `autoencoder` | Latent-space compression tasks | `latent_dim`, `hidden_dim` |
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# Recommended (uv)
+uv add pinnrl
+
+# pip
+pip install pinnrl
+```
+
+Available PDE keys: `heat`, `wave`, `burgers`, `kdv`, `convection`, `allen_cahn`, `cahn_hilliard`, `black_scholes`, `pendulum`.
+
+### Python API — solving the heat equation
+
+```python
+import torch
+from pinnrl.config import Config, ModelConfig, TrainingConfig, EarlyStoppingConfig
+from pinnrl.neural_networks import PINNModel
+from pinnrl.pdes.heat_equation import HeatEquation
+from pinnrl.pdes.pde_base import PDEConfig
+from pinnrl.training.trainer import PDETrainer
+
+device = torch.device("cpu")
+
+training = TrainingConfig(
+    num_epochs=3000, batch_size=2048,
+    num_collocation_points=5000, num_boundary_points=500, num_initial_points=500,
+    learning_rate=1e-3, weight_decay=1e-4, gradient_clipping=1.0,
+    early_stopping=EarlyStoppingConfig(enabled=True, patience=100, min_delta=1e-7),
+    learning_rate_scheduler=None,
+)
+pde_config = PDEConfig(
+    name="heat", domain=[[0.0, 1.0]], time_domain=[0.0, 1.0],
+    parameters={"alpha": 0.01},
+    boundary_conditions={"type": "dirichlet"},
+    initial_condition={"type": "sine", "amplitude": 1.0, "frequency": 2.0},
+    exact_solution={"type": "sin_exp_decay", "amplitude": 1.0, "frequency": 2.0},
+    dimension=1, device=device, training=training,
+)
+config = Config.__new__(Config)
+config.device = device
+config.model = ModelConfig(input_dim=2, hidden_dim=128, output_dim=1,
+                           num_layers=4, activation="tanh", architecture="fourier")
+config.training = training
+config.pde_config = pde_config
+
+pde     = HeatEquation(config=pde_config)
+model   = PINNModel(config=config, device=device)
+trainer = PDETrainer(model=model, pde=pde,
+                     optimizer_config={"learning_rate": 1e-3, "weight_decay": 1e-4},
+                     config=config, device=device)
+trainer.train(num_epochs=3000)
+
+# Validate against exact solution u(x,t) = A * exp(-alpha*(2pi*f/L)^2 * t) * sin(2pi*f*x/L)
+metrics = pde.validate(model, num_points=5000)
+print(f"L2 error: {metrics['l2_error']:.2e}  |  Max error: {metrics['max_error']:.2e}")
+```
+
+
+---
+
+## Features
+
+- **RL-adaptive collocation** — a DQN agent (`src/rl/rl_agent.py`) observes the current residual field and steers point sampling toward high-error regions, reducing wasted forward passes on low-residual areas.
+- **Seven neural architectures** — FeedForward, ResNet, SIREN (periodic activations), Fourier Features (random Fourier mapping), Fourier Neural Operator (spectral convolutions), Self-Attention Transformer, and Autoencoder, all exposed through a single `PINNModel` factory class.
+- **Nine PDEs** — linear to nonlinear, parabolic to hyperbolic, 1D to 2D, spanning thermal diffusion, soliton dynamics, phase-field models, and financial derivatives.
+- **Exact analytical solutions** — every PDE ships with an `exact_solution` method for L2 and max-error validation during and after training; no external reference solver is required.
+- **Adaptive loss weighting** — residual-balancing weights (RBW) and learning-rate-based weights (LRW) automatically re-balance physics, boundary, and initial condition loss terms.
+- **Dash dashboard** — configure and launch experiments, monitor convergence metrics, and compare runs without writing plotting code.
+- **Hardware-aware** — automatically selects CUDA, Apple MPS, or CPU; configurable via the `--device` flag or `config.yaml`.
+
+---
+
+## Comparison with Related Libraries
+
+| Feature | pinnrl | DeepXDE | NeuralPDE.jl |
+|---|---|---|---|
+| RL-based adaptive sampling | Yes | No | No |
+| Architectures bundled | 7 | 3 | 2 |
+| Dashboard trainer | Yes | No | No |
+| Exact solutions built in | Yes | Partial | Partial |
+| Language | Python | Python | Julia |
+| Install | `pip install pinnrl` | `pip install deepxde` | Julia pkg manager |
+
+---
+
+## Roadmap
+
+| Version | Status | Milestones |
+|---|---|---|
+| v0.1 | Now | 9 PDEs, 7 architectures, DQN adaptive sampling, Dash dashboard, exact-solution validation |
+| v0.2 | Planned | PyPI release, 2D/3D geometry, PPO agent option, YAML config schema validation |
+| v0.3 | Planned | Operator learning (DeepONet-style), uncertainty quantification, JAX backend |
+| v1.0 | Future | Stable public API, community PDE registry, full documentation site |
+
+---
+
+## Who Is It For?
+
+- **PhD students and researchers** prototyping mesh-free PDE solvers without implementing adaptive sampling from scratch.
+- **Computational scientists** in fluid dynamics, materials science, or plasma physics benchmarking PINNs against FDM/FEM on standard problems.
+- **Quantitative analysts** exploring neural PDE solvers for high-dimensional option pricing beyond Black-Scholes closed forms.
+- **ML engineers** studying how RL exploration strategies transfer to scientific computing.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue before submitting a large pull request.
+
+**Core development:** Jose Garcia Ventura ([@josegarciav](https://github.com/josegarciav))
+
+**Community contributions** in scope: new PDEs, new architectures, bug fixes, documentation improvements, and example notebooks. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+---
+
+## Citation
+
+If you use `pinnrl` in published work, please cite:
+
+```bibtex
+@software{garcia2024pinnrl,
+  author    = {Garcia Ventura, Jose},
+  title     = {pinnrl: Physics-Informed Neural Networks with Reinforcement Learning Adaptive Sampling},
+  year      = {2024},
+  url       = {https://github.com/josegarciav/PINNs-RL-PDE},
+  note      = {Open-source Python library for mesh-free PDE solving}
+}
+```
+
+---
+
+## License
+
+[MIT License](LICENSE) &copy; 2024 Jose Garcia Ventura

pinnrl-0.1.0/pinnrl/__init__.py

@@ -0,0 +1 @@
+"""Top-level package for PINNs-RL-PDE framework."""

pinnrl-0.1.0/pinnrl/components/adaptive_weights.py

@@ -0,0 +1,134 @@
+import logging
+
+import torch
+
+
+class AdaptiveLossWeights:
+    """Handles adaptive weighting of different loss components in PINNs."""
+
+    def __init__(self, strategy="rbw", alpha=0.9, eps=1e-5, initial_weights=None):
+        """
+        Initialize adaptive loss weights handler.
+
+        Args:
+            strategy (str): Weight adaptation strategy ('lrw' or 'rbw')
+            alpha (float): Moving average factor for weight updates
+            eps (float): Small constant for numerical stability
+            initial_weights (list): Initial weights for [pde, boundary, initial] components
+        """
+        self.strategy = strategy.lower()
+        self.alpha = alpha
+        # Ensure eps is a float, not a string
+        self.eps = float(eps) if isinstance(eps, (str, int)) else eps
+        self.initial_weights = (
+            torch.tensor(initial_weights) if initial_weights is not None else None
+        )
+        self.weights = None
+        self.running_losses = None
+        self.running_grads = None
+        self.logger = logging.getLogger(__name__)
+        self.logger.info(
+            f"AdaptiveLossWeights initialized with strategy={strategy}, alpha={alpha}, eps={self.eps}, initial_weights={initial_weights}"
+        )
+        self.prev_weights = None
+
+    def update_weights_lrw(self, gradients):
+        """
+        Update weights using Learning Rate based Weighting (LRW).
+
+        Args:
+            gradients (list): List of gradient norms for each loss component
+        """
+        if self.running_grads is None:
+            self.running_grads = gradients
+            self.weights = (
+                self.initial_weights.to(gradients.device)
+                if self.initial_weights is not None
+                else torch.ones_like(gradients)
+            )
+            self.logger.info(f"LRW - Initialized weights: {self.weights}")
+            return self.weights
+
+        # Update running average of gradients
+        self.running_grads = self.alpha * self.running_grads + (1 - self.alpha) * gradients
+
+        # Ensure eps is a tensor on the same device as the gradients
+        eps_tensor = torch.tensor(self.eps, device=self.running_grads.device)
+
+        # Compute weights inversely proportional to gradient magnitudes
+        inv_grads = 1.0 / (self.running_grads + eps_tensor)
+        self.weights = inv_grads / torch.sum(inv_grads)
+
+        self.logger.info(
+            f"LRW - Updated weights: gradients={gradients.detach().cpu().numpy()}, running_grads={self.running_grads.detach().cpu().numpy()}, weights={self.weights.detach().cpu().numpy()}"
+        )
+
+        return self.weights
+
+    def update_weights_rbw(self, losses):
+        """
+        Update weights using Relative Error based Weighting (RBW).
+        Gives more weight to terms with bigger losses to balance them.
+
+        Args:
+            losses (list): List of individual loss components
+        """
+        if self.running_losses is None:
+            self.running_losses = losses
+            self.weights = (
+                self.initial_weights.to(losses.device)
+                if self.initial_weights is not None
+                else torch.ones_like(losses)
+            )
+            self.logger.info(f"RBW - Initialized weights: {self.weights}")
+            return self.weights
+
+        # Update running average of losses
+        self.running_losses = self.alpha * self.running_losses + (1 - self.alpha) * losses
+
+        # Ensure eps is a tensor on the same device as the losses
+        eps_tensor = torch.tensor(self.eps, device=self.running_losses.device)
+
+        # Normalize the running losses to get weights
+        # Give more weight to higher losses to focus optimization on problematic terms
+        normalized_losses = self.running_losses / (self.running_losses.sum() + eps_tensor)
+        self.weights = normalized_losses  # Higher loss -> Higher weight
+
+        # Update weights with exponential moving average
+        if self.prev_weights is not None:
+            self.weights = self.alpha * self.prev_weights + (1 - self.alpha) * self.weights
+
+        self.prev_weights = self.weights.clone()
+
+        self.logger.info(
+            f"RBW - Updated weights: losses={losses.detach().cpu().numpy()}, running_losses={self.running_losses.detach().cpu().numpy()}, weights={self.weights.detach().cpu().numpy()}"
+        )
+
+        return self.weights
+
+    def update(self, losses=None, gradients=None):
+        """
+        Update weights based on chosen strategy.
+
+        Args:
+            losses (list): List of individual loss components
+            gradients (list): List of gradient norms for each loss component
+
+        Returns:
+            torch.Tensor: Updated loss weights
+        """
+        if self.strategy == "lrw" and gradients is not None:
+            return self.update_weights_lrw(gradients)
+        elif self.strategy == "rbw" and losses is not None:
+            return self.update_weights_rbw(losses)
+        else:
+            raise ValueError(f"Invalid combination of strategy ({self.strategy}) and inputs")
+
+    def get_weights(self):
+        """Return current weights."""
+        if self.weights is not None:
+            return self.weights
+        elif self.initial_weights is not None:
+            return self.initial_weights
+        else:
+            return torch.ones(3) / 3.0  # Default to equal weights for 3 components