A research-oriented PyTorch framework for implementing and testing Physics-Informed Neural Networks for partial differential equations (PDEs). This repository provides modular implementations with visualization, error analysis, and several sampling strategies.
Physics-Informed Neural Networks (PINNs) embed physical laws described by PDEs directly into neural network loss functions. This approach enables solving forward and inverse PDE problems without requiring large datasets, making it particularly powerful for:
- Scientific Computing: Solve PDEs where traditional methods struggle
- Parameter Estimation: Discover unknown parameters from sparse data
- Multi-Physics Problems: Handle coupled systems naturally
- Real-time Applications: Fast inference once trained
- Heat Equation: 1D diffusion, scored against its closed-form Fourier solution
- Wave Equation: 1D standing waves, second order in time, also exactly solvable
- Burgers Equation: 1D viscous flow with shock formation, validated against the exact ColeβHopf solution
- Navier-Stokes: 2D incompressible flow with periodic boundaries
- Allen-Cahn: Phase field modeling and interface dynamics
- Nonlinear SchrΓΆdinger: Quantum mechanics and nonlinear optics
The heat, wave and Burgers problems have exact solutions, so accuracy is a number rather than a picture.
relative_l2_errorreports it, and the test suite asserts on it β seenotebooks/basic/05_heat_equation.ipynb.
- Continuous-time PINNs: Standard collocation approach
- Discrete-time PINNs: Runge-Kutta integration schemes
- Composable Core API: Problem, geometry, constraint, residual and trainer abstractions for equation-agnostic Burgers/heat/wave training
- SIREN Networks: Sinusoidal representation models for oscillatory fields and coordinate-derivative-heavy PDE residuals
- Nondimensionalization: Characteristic physical scales, derivative scale factors and FP32/FP64-preserving transforms for the composable trainer
- Residual-Adaptive Refinement: Generic trainer support for retaining high-residual collocation points, optional diversity-aware selection and recorded RAR diagnostics
- Composable Sampling: Configurable interior collocation samplers for the generic trainer, with uniform and Latin-hypercube geometry sampling policies plus adapters for legacy sampler interoperability
- Benchmark Provenance: JSON benchmark reports, independent residual scoring, and analytic/numerical/observational reference labels
- RAR Benchmarks: Scripted uniform-vs-adaptive Burgers, heat and wave comparisons using the shared benchmark report schema
- Generic Framework: Easy extension to new PDEs
- GPU Acceleration: CUDA support with automatic detection
- Distributed Training: Data-parallel scaling across multiple GPUs
- Publication-quality plots with Matplotlib/Seaborn
- Spacetime evolution heatmaps and animations
- Error analysis with statistical distributions
- Loss tracking with component breakdown
- Vector field visualization for fluid dynamics
- Latin Hypercube Sampling: Efficient space-filling
- Sobol Sequences: Low-discrepancy sampling
- Adaptive Refinement: Residual-based point addition
- Boundary Sampling: Specialized BC enforcement
- Composite Strategies: Multi-region sampling
- Error Analysis: 10+ accuracy metrics (MAE, RMSE, correlation, etc.)
- Physics Validation: PDE residual analysis
- Statistical Tests: Distribution comparisons, moment analysis
- Convergence Analysis: Richardson extrapolation, rate estimation
- Benchmark Comparison: Multi-method validation
pip install pinnlabThat is the whole solver: torch, numpy, PyYAML and tqdm. Plotting is optional
and lives in the viz extra, along with SciPy and Plotly:
pip install "pinnlab[viz]"import pinnlab does not touch matplotlib, so the base install stays light.
Reach for a plotting helper without the extra and you get an AttributeError
saying which extra to install, rather than a failure further along.
Other extras: dev (tests, linters, docs), gpu, deploy. To work on the
library itself:
git clone https://github.com/DiogoRibeiro7/pinn.git
cd pinn
pip install -e ".[dev,viz]"The distribution is pinnlab, not pinn: that name on PyPI belongs to an
unrelated REST-API client. The import name matches the distribution.
pip install .[dev]
sphinx-build -b html docs docs/_build/htmlExport a trained model to TorchScript and serve it with FastAPI:
PINN_MODEL_PATH=path/to/model.pt uvicorn pinnlab.deployment.server:appDocker and helper scripts for AWS, GCP, and Azure are available under the
deployment/ directory.
from examples.demo_visualization import comprehensive_demo_with_visualization
# Run full demonstration with plots and analysis
comprehensive_demo_with_visualization()from pinnlab.solvers.raissi_improved import ContinuousPINN, demo
# Quick demo
demo()
# Or customize training
from pinnlab.solvers.raissi_improved import MLP, BurgersConfig, TrainConfig
model = MLP(in_dim=2, hidden_layers=8, width=64, out_dim=1)
cfg = BurgersConfig(nu=0.01/np.pi)
tcfg = TrainConfig(n_f=20_000, adam_steps=15_000, lbfgs_max_iter=300)
# Train and get loss history
loss_history = pinn.train(tcfg, weights=(1.0, 1.0, 1.0))from pinnlab.solvers.navier_stokes import demo_tgv
# Taylor-Green vortex simulation
demo_tgv()
# Custom visualization
from pinnlab.utils.visualization import PINNVisualizer
viz = PINNVisualizer()
fig = viz.plot_vector_field_2d(X, Y, U, V, title="Velocity Field")from pinnlab.solvers.raissi_generic import ContinuousPINNGeneric
# Allen-Cahn equation
from pinnlab.solvers.raissi_generic import demo_allen_cahn
demo_allen_cahn()
# Nonlinear SchrΓΆdinger equation
from pinnlab.solvers.raissi_generic import demo_schrodinger
demo_schrodinger()pinn/
βββ π README.md # This guide
βββ πΊοΈ ROADMAP.md # Project status & planned work
βββ π¦ pyproject.toml # Packaging & dependencies
β
βββ π§ src/pinnlab/ # The library
β βββ models/ # MLP, SIREN, Fourier-feature, multi-scale, β¦
β βββ solvers/ # Burgers (continuous + RK), NavierβStokes, generic
β βββ benchmarks/ # Report schema and independent evaluators
β βββ numerics/ # Classical numerical reference solvers
β βββ sampling/ # Latin-Hypercube, importance, active learning
β βββ training/ # Adaptive weighting, curriculum, meta-learning, β¦
β βββ transfer/ # Pre-training, fine-tuning, distillation, domain adaptation
β βββ uncertainty/ # Ensembles, MC-dropout, Bayesian, GP priors
β βββ distributed/ # Data-parallel trainer, gradient compression, load balancing
β βββ optimization/ # Caching & computation reuse
β βββ deployment/ # REST/gRPC model serving, model I/O
β βββ visualization/ # Plotting toolkit & training dashboard
β βββ utils/ # Metrics, checkpointing, profiling, validation
β βββ config/ # Configuration management
β
βββ π¨ examples/ # Runnable scripts (basic / advanced / benchmarks)
βββ π notebooks/ # Self-contained, executed Kaggle-style tutorials
βββ π§ͺ tests/ # Test suite
βββ π docs/ # Sphinx documentation
βu/βt + uΒ·βu/βx - Ξ½Β·βΒ²u/βxΒ² = 0
- Domain: 1D spatial [-1,1], temporal [0,1]
- BC: Dirichlet (u = 0 at boundaries)
- IC: u(0,x) = -sin(Οx)
- Applications: Shock wave formation, traffic flow
βu/βt + (uΒ·β)u + βp - Ξ½βΒ²u = 0 (momentum)
βΒ·u = 0 (continuity)
- Domain: 2D spatial [0,2Ο]Γ[0,2Ο], temporal
- BC: Periodic boundaries
- Test Case: Taylor-Green vortex (analytical solution)
- Applications: Fluid dynamics, weather prediction
βu/βt - Ξ½Β·βΒ²u/βxΒ² + (uΒ³ - u) = 0
- Domain: 1D spatial, temporal
- BC: Dirichlet (customizable)
- Applications: Phase transitions, material interfaces
iΒ·βu/βt + Β½Β·βΒ²u/βxΒ² + |u|Β²u = 0
- Domain: 1D spatial, temporal
- Representation: Complex field as [Re(u), Im(u)]
- Applications: Quantum mechanics, nonlinear optics
from pinnlab.utils.visualization import quick_plot_loss
loss_history = {
"total": [...], # Total weighted loss
"pde": [...], # PDE residual loss
"ic": [...], # Initial condition loss
"bc": [...] # Boundary condition loss
}
fig = quick_plot_loss(loss_history, "Training Progress")from pinnlab.utils.visualization import PINNVisualizer
viz = PINNVisualizer()
# Spacetime heatmap
fig = viz.plot_spacetime_1d(t_grid, x_grid, u_solution,
title="Solution Evolution")
# Error analysis with statistics
fig = viz.plot_error_analysis(x, u_pred, u_true,
title="Comprehensive Error Analysis")# 2D vector fields (e.g., velocity)
fig = viz.plot_vector_field_2d(X, Y, U, V,
title="Navier-Stokes Velocity Field",
skip=3, scale=1.0)from pinnlab.sampling import create_lhs_sampler
# Efficient space-filling sampling
sampler = create_lhs_sampler(bounds=[(-1,1), (0,1)], seed=123)
points = sampler.sample(10000)from pinnlab.sampling import AdaptiveSampler
# Residual-based adaptive sampling
adaptive_sampler = AdaptiveSampler(domain, residual_fn, base_sampler)
refined_points = adaptive_sampler.sample(5000)from pinnlab.sampling import create_boundary_points
# Specialized boundary sampling
boundaries = create_boundary_points(
bounds=[(-1,1), (0,1)],
n_points_per_face=200
)from pinnlab.utils.metrics import quick_error_summary, validate_pinn_solution
# Fast error overview
print(quick_error_summary(y_true, y_pred))
# Validation against tolerances
pass_fail, results, summary = validate_pinn_solution(
y_true, y_pred, residuals,
tolerance={"rmse": 1e-3, "correlation": 0.98}
)from pinnlab.utils.metrics import comprehensive_error_analysis, generate_metrics_report
# Full error analysis
results = comprehensive_error_analysis(
y_true, y_pred,
coordinates=coords,
residuals=residuals
)
# Generate formatted report
report = generate_metrics_report(results, "Burgers Equation Analysis")
print(report)from pinnlab.utils.metrics import ConvergenceAnalysis
# Analyze convergence rates
analyzer = ConvergenceAnalysis()
convergence_rates = analyzer.analyze_convergence(
resolutions=[1000, 2000, 4000, 8000],
errors={"rmse": [1e-2, 5e-3, 2.5e-3, 1.2e-3]}
)def my_pde_residual(model, t, x):
"""Custom PDE: βu/βt + Ξ±Β·u + Ξ²Β·βΒ²u/βxΒ² = f(t,x)"""
# Enable gradients
t = t.clone().detach().requires_grad_(True)
x = x.clone().detach().requires_grad_(True)
# Network prediction
u = model(torch.cat([t, x], dim=1))
# Compute derivatives using autograd
u_t = torch.autograd.grad(u, t, torch.ones_like(u),
retain_graph=True, create_graph=True)[0]
u_x = torch.autograd.grad(u, x, torch.ones_like(u),
retain_graph=True, create_graph=True)[0]
u_xx = torch.autograd.grad(u_x, x, torch.ones_like(u_x),
retain_graph=True, create_graph=True)[0]
# PDE residual
alpha, beta = 0.1, 0.01
source_term = torch.sin(t) * torch.cos(x) # Example source
residual = u_t + alpha * u + beta * u_xx - source_term
return residualfrom pinnlab.solvers.raissi_generic import ContinuousPINNGeneric
from pinnlab.sampling import Domain
# Setup domain and model
domain = Domain(bounds=[(0, 1), (-1, 1)], names=['t', 'x'])
model = MLP(in_dim=2, hidden_layers=8, width=64, out_dim=1)
# Create PINN
pinn = ContinuousPINNGeneric(
model=model,
device="cuda",
domain=domain,
u_dim=1,
u0_fn=lambda x: np.sin(np.pi * x), # Initial condition
bc_left_fn=lambda t: np.zeros_like(t), # Left boundary
bc_right_fn=lambda t: np.zeros_like(t), # Right boundary
residual_fn=my_pde_residual # Your PDE residual
)
# Train with comprehensive tracking
loss_history = pinn.train(
n_u0=200, n_bc=200, n_f=20_000,
lr=1e-3, steps=15_000, lbfgs_max_iter=300
)@dataclass
class OptimalTrainConfig:
# Sampling points
n_u0: int = 200 # Initial condition points
n_bc: int = 200 # Boundary points per face
n_f: int = 20_000 # PDE collocation points (increase for accuracy)
# Optimization
lr: float = 1e-3 # Adam learning rate
adam_steps: int = 15_000 # Adam iterations (8k-20k typical)
lbfgs_max_iter: int = 300 # L-BFGS polish (0 to disable)
# Loss weighting (tune for balance)
w_ic: float = 1.0 # Initial condition weight
w_bc: float = 1.0 # Boundary condition weight
w_pde: float = 1.0 # PDE residual weight
# Reproducibility
seed: int = 123- π― Sampling Strategy:
- Use Latin Hypercube for collocation points
- More boundary points for complex BCs
- Adaptive refinement in high-gradient regions
- π§ Network Architecture:
- Start with 8 layers Γ 64 neurons
- Tanh activation for smooth derivatives
- Xavier initialization for stability
- ποΈ Training Strategy:
- Adam (15k steps) β L-BFGS (300 steps)
- Monitor loss components separately
- Early stopping if residuals plateau
- βοΈ Loss Balancing:
- Equal weights initially (1:1:1)
- Increase PDE weight if residuals are high
- Increase BC weight if boundaries not satisfied
β_total = Ξ»_IC Β· β_IC + Ξ»_BC Β· β_BC + Ξ»_PDE Β· β_PDE
Where:
- β_IC = MSE(u_ΞΈ(tβ,x), uβ(x)): Initial condition loss (supervised)
- β_BC = MSE(u_ΞΈ(t,x_b), g(t)): Boundary condition loss (supervised)
- β_PDE = MSE(f_ΞΈ(t,x), 0): PDE residual loss (unsupervised physics)
PINNs leverage automatic differentiation to compute exact derivatives:
# First derivative: βu/βt
u_t = torch.autograd.grad(u, t, grad_outputs=torch.ones_like(u),
retain_graph=True, create_graph=True)[0]
# Second derivative: βΒ²u/βxΒ²
u_x = torch.autograd.grad(u, x, torch.ones_like(u),
retain_graph=True, create_graph=True)[0]
u_xx = torch.autograd.grad(u_x, x, torch.ones_like(u_x),
retain_graph=True, create_graph=True)[0]- Meshfree: No spatial/temporal discretization
- Flexible Geometry: Irregular domains handled naturally
- Multi-scale: Captures multiple time/length scales
- Inverse Problems: Parameter estimation from sparse data
If you use this library in academic work, please cite it. Each release is archived on Zenodo, and the DOI below is the concept DOI: it always resolves to the most recent version, so it is the right one to cite when you mean the software in general.
@software{ribeiro_pinn,
author = {Ribeiro, Diogo},
title = {{pinn}: A Modular PyTorch Framework for Physics-Informed Neural Networks},
year = {2026},
version = {0.6.1},
publisher = {Zenodo},
doi = {10.5281/zenodo.21844101},
url = {https://doi.org/10.5281/zenodo.21844101}
}To cite the exact version you used rather than the software as a whole, take the version-specific DOI from that release's Zenodo record and substitute it above.
Machine-readable metadata is provided in CITATION.cff, from which GitHub
renders a "Cite this repository" button, and in .zenodo.json, which
Zenodo reads when it archives a tagged release. Both are validated in CI.
-
Raissi, M., Perdikaris, P., & Karniadakis, G. E. (2019). Physics-informed neural networks: A deep learning framework for solving forward and inverse problems involving nonlinear partial differential equations. Journal of Computational Physics, 378, 686-707.
-
Raissi, M., Perdikaris, P., & Karniadakis, G. E. (2018). Numerical Gaussian processes for time-dependent and nonlinear partial differential equations. SIAM Journal on Scientific Computing, 40(1), A172-A198.
-
Raissi, M., Perdikaris, P., & Karniadakis, G. E. (2017). Physics Informed Deep Learning (Part I): Data-driven Solutions of Nonlinear Partial Differential Equations. arXiv preprint arXiv:1711.10561.
-
Raissi, M., Perdikaris, P., & Karniadakis, G. E. (2017). Physics Informed Deep Learning (Part II): Data-driven Discovery of Nonlinear Partial Differential Equations. arXiv preprint arXiv:1711.10566.
@article{raissi2019physics,
title={Physics-informed neural networks: A deep learning framework for solving forward and inverse problems involving nonlinear partial differential equations},
author={Raissi, Maziar and Perdikaris, Paris and Karniadakis, George Em},
journal={Journal of Computational Physics},
volume={378},
pages={686--707},
year={2019},
publisher={Elsevier}
}
@article{raissi2018numerical,
title={Numerical Gaussian processes for time-dependent and nonlinear partial differential equations},
author={Raissi, Maziar and Perdikaris, Paris and Karniadakis, George Em},
journal={SIAM Journal on Scientific Computing},
volume={40},
number={1},
pages={A172--A198},
year={2018},
publisher={SIAM}
}
@article{raissi2017physicsI,
title={Physics Informed Deep Learning (Part I): Data-driven Solutions of Nonlinear Partial Differential Equations},
author={Raissi, Maziar and Perdikaris, Paris and Karniadakis, George Em},
journal={arXiv preprint arXiv:1711.10561},
year={2017}
}
@article{raissi2017physicsII,
title={Physics Informed Deep Learning (Part II): Data-driven Discovery of Nonlinear Partial Differential Equations},
author={Raissi, Maziar and Perdikaris, Paris and Karniadakis, George Em},
journal={arXiv preprint arXiv:1711.10566},
year={2017}
}See ROADMAP.md for the current status of the library and what's planned next β new PDE solvers and architectures, GPU/multi-node validation, richer uncertainty quantification, and documentation. Contributions toward any roadmap item are very welcome.
We welcome contributions! Please see our Contributing Guidelines for details.
The notebooks/ folder contains self-contained, executed tutorials in a narrative,
Kaggle-style format β theory in LaTeX, runnable code, and baked-in plots and metrics. Each runs
end-to-end on a laptop CPU in a minute or two.
- Core β getting started, the visualization toolkit, and sampling & metrics
basic/β Burgers, AllenβCahn (custom residual), a reusable PDE template, and 2-D NavierβStokesadvanced/β inverse problems, uncertainty quantification, multi-scale/curriculum training, and distributed trainingbenchmarks/β active learning, convergence, loss weighting, spectral bias, performance, and transfer learning
Start with notebooks/01_getting_started.ipynb and follow the
guided path in the notebooks README. The standalone scripts the notebooks are
based on live in examples/.
# Clone and set up a development environment
git clone https://github.com/DiogoRibeiro7/pinn.git
cd pinn
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install with the development and visualisation extras. `viz` is not needed to
# import the package -- plotting is imported lazily -- but the examples,
# notebooks and a few tests do plot.
pip install -e ".[dev,viz]"
# Optional: run the formatting and lint checks on every commit
pre-commit install
# Run the checks CI runs
pytest
black --check .
flake8 .
bandit -r src -llSee CONTRIBUTING.md for the full workflow, and SECURITY.md before deploying the serving layer or loading a checkpoint you did not produce yourself.
- π¬ New PDE implementations
- π¨ Visualization enhancements
- π Additional metrics and analysis tools
- π Documentation and tutorials
- πββοΈ Performance optimizations
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: dfr@esmad.ipp.pt
- Documentation: Full Documentation
- Original PINN framework by Raissi, Perdikaris, and Karniadakis
- PyTorch team for automatic differentiation capabilities
- Scientific computing community for continuous inspiration
β Star this repository if you find it useful for your research!
π Read the full documentation at DiogoRibeiro7.github.io/pinn
