Distributions ============== Every distribution below implements ``log_prob``, a reparameterized ``sample`` where possible, and closed-form ``mean``/``variance``/ ``quantile`` where they exist in closed form. Parameters may themselves be :class:`~prophys.symbolic.Expr` (typically :class:`~prophys.symbolic.Param`), so a distribution's shape can be learned or driven by upstream geometry. Each family below is shown with its probability-density plots and, where useful, parameter-sensitivity sweeps. Univariate ----------- .. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: Gaussian :img-top: /_static/gallery/distributions/gaussian_pdf.png ``Gaussian(mean, sigma)`` .. grid-item-card:: Weibull :img-top: /_static/gallery/distributions/weibull_pdf.png ``Weibull(scale, concentration)`` .. grid-item-card:: Exponential :img-top: /_static/gallery/distributions/exponential_pdf.png ``Exponential(rate)`` .. grid-item-card:: LogNormal :img-top: /_static/gallery/distributions/lognormal_pdf.png ``LogNormal(mu, sigma)`` .. grid-item-card:: Gamma :img-top: /_static/gallery/distributions/gamma_pdf.png ``Gamma(concentration, rate)`` .. grid-item-card:: Beta :img-top: /_static/gallery/distributions/beta_pdf.png ``Beta(alpha, beta)`` .. grid-item-card:: Uniform :img-top: /_static/gallery/distributions/uniform_pdf.png ``Uniform(low, high)`` .. grid-item-card:: Gumbel :img-top: /_static/gallery/distributions/gumbel_pdf.png ``Gumbel(loc, scale)`` .. grid-item-card:: TruncatedGaussian :img-top: /_static/gallery/distributions/truncated_gaussian_pdf.png ``TruncatedGaussian(mean, sigma, low, high)`` Parameter sensitivity ~~~~~~~~~~~~~~~~~~~~~~~ Each univariate distribution also has a small-multiples sensitivity panel and per-parameter sweeps, e.g.: .. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: :img-top: /_static/gallery/distributions/weibull_sensitivity.png Weibull — parameter sensitivity grid .. grid-item-card:: :img-top: /_static/gallery/distributions/gaussian_sigma_sweep.png Gaussian — effect of sigma Cumulative distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~ Closed-form quantiles give exact CDFs (Gaussian, Weibull, Exponential, Uniform, Gumbel); the remaining families are integrated numerically. .. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: :img-top: /_static/gallery/distributions/weibull_cdf.png Weibull — CDF (closed-form quantile) .. grid-item-card:: :img-top: /_static/gallery/distributions/gamma_cdf.png Gamma — CDF (numeric) .. autoclass:: prophys.distributions.Gaussian :members: .. autoclass:: prophys.distributions.Weibull :members: .. autoclass:: prophys.distributions.Exponential :members: .. autoclass:: prophys.distributions.LogNormal :members: .. autoclass:: prophys.distributions.Gamma :members: .. autoclass:: prophys.distributions.Beta :members: .. autoclass:: prophys.distributions.Uniform :members: .. autoclass:: prophys.distributions.Gumbel :members: .. autoclass:: prophys.distributions.TruncatedGaussian :members: .. autoclass:: prophys.distributions.Bernoulli :members: .. autoclass:: prophys.distributions.Poisson :members: .. autoclass:: prophys.distributions.Categorical :members: Circular --------- For angular quantities like wind direction, where ordinary Gaussians are wrong because :math:`0` and :math:`2\pi` are the same point. .. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: VonMises — concentration sweep :img-top: /_static/gallery/circular/vonmises_kappa.png Higher ``kappa`` -> more concentrated around ``loc``. .. grid-item-card:: WrappedGaussian — sigma sweep :img-top: /_static/gallery/circular/wrapped_gaussian.png A Gaussian wrapped onto the circle. .. autoclass:: prophys.distributions.VonMises :members: .. autoclass:: prophys.distributions.WrappedGaussian :members: Directional climatologies ------------------------------ :class:`~prophys.distributions.DirectionalMixture` is the standard representation of a directional climatology — wind rose, wave rose, current regime, or any other joint distribution of "which direction" and "how strong": the circle is divided into sectors, each with an occurrence weight, a circular spread (a :class:`~prophys.distributions.VonMises` around the sector center), and its own conditional intensity distribution (e.g. a per-sector :class:`~prophys.distributions.Weibull` of wind speed). All parameters — sector weights, spreads, and every conditional intensity distribution's parameters — are ordinary ``Expr``\ s, so a climatology fitted from met-mast or reanalysis observations is a single :func:`~prophys.engine.fit_distribution` call, and its sector weights can just as well be design variables (e.g. trading off wake losses against a site's directional wind resource). .. code-block:: python import jax.numpy as jnp import prophys as prp sector_speeds = [ prp.Weibull(scale=prp.Param(f"scale_{i}", init=7.0), concentration=2.0) for i in range(8) ] wind_rose = prp.DirectionalMixture.evenly_spaced( weights=prp.Param("sector_weights", shape=(8,), init=jnp.full((8,), 1 / 8)), intensities=sector_speeds, ) wind_rose.log_prob(direction=jnp.deg2rad(200.0), intensity=9.5) .. autoclass:: prophys.distributions.DirectionalMixture :members: Multivariate & mixtures -------------------------- .. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: MultivariateGaussian :img-top: /_static/gallery/multivariate/mvn_corr_pos08.png Cholesky-parameterized covariance — always positive-definite under gradient updates. .. grid-item-card:: Mixture :img-top: /_static/gallery/multivariate/mixture_weight_overlay.png Finite mixture with softmax-normalized weights. .. grid-item-card:: Empirical :img-top: /_static/gallery/multivariate/empirical_kde.png Kernel-density estimate from raw samples — stays differentiable. .. grid-item-card:: Histogram :img-top: /_static/gallery/multivariate/histogram.png Piecewise-constant density from bin edges/probabilities. .. autoclass:: prophys.distributions.MultivariateGaussian :members: .. autoclass:: prophys.distributions.Mixture :members: .. autoclass:: prophys.distributions.Empirical :members: .. autoclass:: prophys.distributions.Histogram :members: Copulas & dependence structures ------------------------------------ A :class:`~prophys.distributions.GaussianCopula` couples arbitrary marginals (each just needs a ``quantile`` method) through a correlation matrix that is parameterized so it is *always* valid — an unconstrained gradient step can never produce a non-positive-definite correlation matrix. .. grid:: 1 3 3 3 :gutter: 2 .. grid-item-card:: rho = -0.7 :img-top: /_static/gallery/copula/copula_gaussian_weibull_neg.png .. grid-item-card:: rho = 0 :img-top: /_static/gallery/copula/copula_gaussian_weibull_zero.png .. grid-item-card:: rho = +0.7 :img-top: /_static/gallery/copula/copula_gaussian_weibull_pos.png .. autoclass:: prophys.distributions.GaussianCopula :members: .. autoclass:: prophys.distributions.Correlation :members: .. autoclass:: prophys.distributions.Independent :members: Discrete distributions -------------------------- .. grid:: 1 2 2 2 :gutter: 2 .. grid-item-card:: Poisson :img-top: /_static/gallery/discrete/poisson_pmf.png .. grid-item-card:: Bernoulli :img-top: /_static/gallery/discrete/bernoulli_pmf.png