prophys Documentation ====================== .. image:: _static/prophys-logo.png :alt: prophys logo :width: 110px :align: right **A JAX-native, fully differentiable symbolic DSL for spatial probability and risk models.** prophys lets you describe an uncertainty structure with geometry, physics, and probability distributions. It offers a symbolic Python DSL, and compiles models into a ``jit``/``grad``/``vmap``-able model with calibration, design optimization, and a standardized export format. It is not a distribution library like NumPyro or Distrax but rather sits in the layer *above* one, combining differentiable geometry (distances to polygons, point sets, lines, 3D exclusion volumes, voxel fields, unstructured meshes, directed networks), transformations, differentiable discrete design decisions, and probabilistic attributes, including directional climatologies like wind/wave roses, in a single compiled graph. prophys is proprietary software by RhineQC GmbH. .. grid:: 1 1 2 2 :gutter: 3 .. grid-item-card:: .. image:: /_static/gallery/distributions/compare_heavy_tails.png :target: distributions.html :width: 100% **Distribution catalog.** Gaussian, Weibull, Gamma, Beta, circular (VonMises), multivariate, mixtures, and Gaussian copulas — all differentiable. :doc:`Browse the catalog → ` .. grid-item-card:: .. image:: /_static/generated/gas_dispersion_risk_map.png :target: examples/gas_dispersion.html :width: 100% **A complete worked model.** A gas-dispersion community health-risk model exercising every primitive family end to end. :doc:`See the example → ` .. grid-item-card:: **Networks, discrete design, and cascades.** A distribution-grid reinforcement model: directed-graph topology, differentiable binary reinforcement decisions, and a multi-hop fault cascade, jointly optimized against continuous substation siting. :doc:`See the example → ` One toolkit, many domains -------------------------- prophys is not a physics package for one vertical — the same primitives that built the gas-dispersion example also built the electric-grid cascade, and compose just as directly into wake models, catastrophe pricing, or tail-risk layers. What the library actually offers is **differentiability and joint calibration/optimization over geometry + physics + uncertainty**, whatever the domain: .. grid:: 1 2 3 3 :gutter: 3 .. grid-item-card:: Gas dispersion & health risk :img-top: /_static/generated/gas_dispersion_complaint_landscape.png :link: examples/gas_dispersion :link-type: doc A plume surrogate over terrain ``Field``\ s and ``Polygon`` zones, wind as upstream ``RandomVariable``\ s, dose-response calibration, abatement optimized under a compliance constraint. .. grid-item-card:: Power-grid fault cascades :link: examples/electric_grid :link-type: doc A directed ``Network`` cascade where each line's reinforcement is a differentiable ``BinaryState`` — discrete topology decisions and continuous substation siting optimized in one gradient pass. .. grid-item-card:: Wind & wave climatologies :img-top: /_static/gallery/circular/vonmises_kappa.png :link: distributions :link-type: doc ``DirectionalMixture`` couples sector weights, circular spread, and per-sector intensity (e.g. Weibull wind speeds) — a calibratable wind rose feeding turbine-siting or fatigue-load models. .. grid-item-card:: Flood & catastrophe pricing :img-top: /_static/gallery/copula/copula_gaussian_weibull_pos.png :link: distributions :link-type: doc Terrain rasters and portfolio ``Polygon``\ s under a ``GaussianCopula`` coupling hazard marginals — spatially correlated loss, differentiable end to end for pricing sensitivities. .. grid-item-card:: Insurance tail risk :img-top: /_static/gallery/distributions/compare_heavy_tails.png :link: calibration :link-type: doc Heavy-tailed severity (``Gumbel``, ``LogNormal``, mixtures) with ``quantile()``/``cvar()`` on any compiled attribute — attachment points and layer structures tuned by gradient. .. grid-item-card:: FEM/CFD surrogate ingestion :img-top: /_static/generated/gas_dispersion_terrain.png :link: structures :link-type: doc Solver outputs land in a ``Mesh`` (P1 barycentric) or voxel ``Field3D`` and become differentiable model inputs — calibrate a simulated stress or concentration field against point observations. .. grid-item-card:: Pipeline & route safety :link: structures :link-type: doc A ``Polyline``'s route is a ``Param``; a leak location is a continuous, reparameterized draw along it via ``point_at`` — siting and leak-exposure liability optimized jointly, not approximated by a hand-picked grid of candidate leak points. .. grid:: 2 2 3 3 :gutter: 3 .. grid-item-card:: Concepts :link: concepts :link-type: doc Symbolic graphs, frames, eval vs. opt mode, and Monte-Carlo marginalization explained. .. grid-item-card:: Structures :link: structures :link-type: doc Point, Line, Polygon, Polyhedron, Field, Grid, Network, Field3D, and Mesh — every differentiable geometry primitive. .. grid-item-card:: Distributions :link: distributions :link-type: doc Univariate, circular, multivariate, mixture, and copula distributions, with plots. .. grid-item-card:: Transformations :link: transformations :link-type: doc Linear, piecewise-linear, decay, logistic, and table-lookup transforms. .. grid-item-card:: Calibration & Design :link: calibration :link-type: doc Fit parameters to observations and optimize design variables with Optax, entirely through gradients. .. grid-item-card:: Export Format :link: export_format :link-type: doc The standardized, consumer-agnostic ``ModelPackage`` interchange format for a compiled model. Minimal Working Example ------------------------ .. code-block:: python import prophys as prp import jax.numpy as jnp site = prp.Frame("site") houses = prp.PointList(jnp.array([[0.0, 0.0], [200.0, 0.0]]), site) turbines = prp.PointList(prp.Param("pos", shape=(2, 2), init=jnp.array([[80.0, 80.0], [150.0, 20.0]])), site) distance = houses.closest_distance(turbines, mode="opt", tau=2.0) level = prp.Param("base", init=100.0) - 20 * prp.log10(distance) acceptance = prp.UncertainAttribute("acceptance_drop", prp.Weibull(scale=1.0 + level, concentration=prp.Param("k", init=2.0))) model = prp.ProbabilityModel(acceptance) compiled = model.compile(mode="opt") print(compiled.expectation("acceptance_drop")) Where To Start --------------- - Installation: :doc:`installation` - License and the free tier: :doc:`license` - Core concepts: :doc:`concepts` - Geometry primitives: :doc:`structures` - Distribution catalog (with plots): :doc:`distributions` - Transformation catalog (with plots): :doc:`transformations` - Calibration and design optimization: :doc:`calibration` - The gas-dispersion worked example: :doc:`examples/gas_dispersion` - The electric-grid worked example: :doc:`examples/electric_grid` - Standardized export format: :doc:`export_format` - Full API reference: :doc:`api` .. toctree:: :maxdepth: 2 :hidden: installation license concepts structures distributions transformations calibration examples/gas_dispersion examples/electric_grid export_format api imprint