Package jdistlib

Class NumericalContinuousDistribution

java.lang.Object
jdistlib.generic.GenericDistribution
jdistlib.NumericalContinuousDistribution
All Implemented Interfaces:
SupportedDistribution
public class NumericalContinuousDistribution extends GenericDistribution implements SupportedDistribution
A continuous distribution obtained by numerically normalizing a nonnegative kernel over a real interval.

If kernel is g, this class uses the density g(x) / Z, where Z = integral(g(x), lower, upper). Bounds may be finite or infinite. The normalization integral is evaluated once during construction; CDF values and quantiles are evaluated numerically on demand. The supplied function must remain deterministic and thread-safe if the distribution is shared between threads.

Successful numerical integration cannot prove that an arbitrary function is nonnegative or integrable everywhere. Kernel values encountered by the integrator are checked, and the normalization result is available through getNormalizationResult() for inspection.

  • Constructor Details

    • NumericalContinuousDistribution

      public NumericalContinuousDistribution(UnivariateFunction kernel, double lower, double upper)
      Constructs a distribution using distribution-oriented integration defaults: relative tolerance 1e-10, 300 subdivisions, a finite evaluation budget, and automatic finite-interval tanh-sinh fallback.
      Parameters:
      kernel - nonnegative unnormalized density
      lower - lower support bound, possibly negative infinity
      upper - upper support bound, possibly positive infinity
      Throws:
      IllegalArgumentException - if the support or normalization is invalid

    • NumericalContinuousDistribution

      public NumericalContinuousDistribution(UnivariateFunction kernel, double lower, double upper, double epsabs, double epsrel, int subdivisions)
      Constructs a distribution with explicit QUADPACK tolerances.
      Parameters:
      kernel - nonnegative unnormalized density
      lower - lower support bound, possibly negative infinity
      upper - upper support bound, possibly positive infinity
      epsabs - absolute integration tolerance
      epsrel - relative integration tolerance
      subdivisions - maximum number of integration subdivisions
      Throws:
      IllegalArgumentException - if the inputs or normalization are invalid

    • NumericalContinuousDistribution

      public NumericalContinuousDistribution(UnivariateFunction kernel, double lower, double upper, IntegrationOptions options)
      Constructs a distribution with hardened integration options.

  • Method Details

    • builder

      public static NumericalContinuousDistribution.Builder builder()
      Returns a fluent builder for a custom continuous distribution.

    • fromLogKernel

      public static NumericalContinuousDistribution fromLogKernel(UnivariateFunction logKernel, double lower, double upper)
      Constructs from a log-kernel, automatically selecting a finite reference value from deterministic interior probes.

    • fromLogKernel

      public static NumericalContinuousDistribution fromLogKernel(UnivariateFunction logKernel, double lower, double upper, IntegrationOptions options)
      Constructs from a log-kernel with explicit integration options.

    • fromLogKernel

      public static NumericalContinuousDistribution fromLogKernel(UnivariateFunction logKernel, double lower, double upper, double referenceLogValue, IntegrationOptions options)
      Constructs from a log-kernel with a user-supplied finite scaling reference.

    • analyze

      public static NumericalDistributionBuildResult analyze(UnivariateFunction kernel, double lower, double upper)
      Analyzes a kernel and attempts construction using the analyzer's integration settings plus any suggested breakpoints. The retained report remains advisory rather than a proof of validity.

    • analyze

      public static NumericalDistributionBuildResult analyze(UnivariateFunction kernel, double lower, double upper, ConstructionPolicy policy)
      Analyzes using defaults and an explicit construction policy.

    • analyze

      public static NumericalDistributionBuildResult analyze(UnivariateFunction kernel, double lower, double upper, FunctionAnalysisOptions analysisOptions)
      Analyzes and attempts construction with explicit analysis settings.

    • analyzeLogKernel

      public static NumericalDistributionBuildResult analyzeLogKernel(UnivariateFunction logKernel, double lower, double upper)
      Analyzes a log-kernel in log space and attempts construction using the default settings. Negative infinity is accepted as zero mass.

    • analyzeLogKernel

      public static NumericalDistributionBuildResult analyzeLogKernel(UnivariateFunction logKernel, double lower, double upper, ConstructionPolicy policy)
      Analyzes a log-kernel with defaults and an explicit policy.

    • analyzeLogKernel

      public static NumericalDistributionBuildResult analyzeLogKernel(UnivariateFunction logKernel, double lower, double upper, FunctionAnalysisOptions analysisOptions)
      Analyzes and attempts log-kernel construction with explicit settings.

    • analyzeDistribution

      public DistributionAnalysis analyzeDistribution()
      Runs CDF, quantile, tail, normalization, and moment diagnostics.

    • analyzeDistribution

      public DistributionAnalysis analyzeDistribution(MomentAnalysisOptions settings)
      Runs diagnostics with user-selected absolute-moment orders and tail split.

    • getLowerBound

      public double getLowerBound()
      Returns the lower support bound.
      Specified by:
      getLowerBound in interface SupportedDistribution

    • getUpperBound

      public double getUpperBound()
      Returns the upper support bound.
      Specified by:
      getUpperBound in interface SupportedDistribution

    • getIntegrationOptions

      public IntegrationOptions getIntegrationOptions()
      Returns the immutable integration settings used by this distribution.

    • getLogScalingRegionCount

      public int getLogScalingRegionCount()
      Number of independently scaled regions used for an automatic log-kernel.

    • getNormalizationConstant

      public double getNormalizationConstant()
      Returns the cached normalization constant.

    • getLogNormalizationConstant

      public double getLogNormalizationConstant()
      Returns the logarithm of the cached normalization constant.

    • getNormalizationResult

      public IntegrationResult getNormalizationResult()
      Returns a defensive copy of the normalization diagnostics. For a log-kernel, its result and error describe the scaled integral actually sent to the quadrature routine; getLogNormalizationConstant() describes the original formula's normalizer.

    • getImmutableNormalizationResult

      public ImmutableIntegrationResult getImmutableNormalizationResult()
      Returns immutable normalization diagnostics without retaining the kernel.

    • getCdfTable

      public NumericalCdfTable getCdfTable()
      Returns the lazily built reusable monotone CDF table.

    • rebuildCdfTable

      public NumericalCdfTable rebuildCdfTable(CdfTableOptions settings)
      Rebuilds and installs the reusable CDF table with explicit settings.

    • clearCdfTable

      public void clearCdfTable()
      Drops the table so the next CDF or central quantile call rebuilds it.

    • density

      public double density(double x, boolean log)
      Specified by:
      density in class GenericDistribution

    • cumulative

      public double cumulative(double x, boolean lowerTail, boolean logP)
      Specified by:
      cumulative in class GenericDistribution

    • cumulativeInto

      public void cumulativeInto(double[] input, int inputOffset, double[] output, int outputOffset, int length, boolean lowerTail, boolean logP)
      Batch CDF evaluation reuses the monotone table for ordinary probabilities.
      Overrides:
      cumulativeInto in class GenericDistribution

    • cumulativeCached

      public double cumulativeCached(double x, boolean lowerTail, boolean logP)
      Evaluates through the reusable CDF table. Extreme or logged tails fall back to direct integration to avoid subtractive loss.

    • quantile

      public double quantile(double p, boolean lowerTail, boolean logP)
      Specified by:
      quantile in class GenericDistribution

    • random

      public double random()
      Specified by:
      random in class GenericDistribution

    • configureRejectionSampling

      public void configureRejectionSampling(RejectionEnvelope envelope, int maxAttempts)
      Configures rejection-envelope sampling for subsequent random() calls. The caller is responsible for the envelope's global majorization promise; sampled violations are detected and rejected with an exception.

    • configureUniformRejectionSampling

      public void configureUniformRejectionSampling(double logDensityUpperBound, int maxAttempts)
      Configures a uniform rejection envelope over this finite support.

    • clearRejectionSampling

      public void clearRejectionSampling()
      Restores inverse-CDF sampling.

    • isRejectionSamplingConfigured

      public boolean isRejectionSamplingConfigured()

    • configureAdaptiveRejectionSampling

      public void configureAdaptiveRejectionSampling(UnivariateFunction logDerivative, int maximumKnots, int maximumAttempts, double... initialPoints)
      Configures adaptive rejection under a caller-certified log-concavity promise.

    • clearAdaptiveRejectionSampling

      public void clearAdaptiveRejectionSampling()

    • isAdaptiveRejectionSamplingConfigured

      public boolean isAdaptiveRejectionSamplingConfigured()

    • getSamplingStrategy

      public SamplingStrategy getSamplingStrategy()

    • getSamplingStrategyExplanation

      public String getSamplingStrategyExplanation()

    • expectation

      public ImmutableIntegrationResult expectation(UnivariateFunction function)
      Numerically evaluates E[g(X)] with immutable integration diagnostics.

    • rawMoment

      public ImmutableIntegrationResult rawMoment(double order)
      Numerically evaluates E[X^order]. Fractional orders require nonnegative support.

    • centralMoment

      public ImmutableIntegrationResult centralMoment(double order)
      Numerically evaluates E[(X-E[X])^order]. Orders must be integers.

    • entropy

      public ImmutableIntegrationResult entropy()
      Numerically evaluates differential entropy, -E[log f(X)].

    • mode

      public double mode()
      Returns the best mode observed by transformed-grid search and refinement.

    • probabilityInterval

      public ProbabilityInterval probabilityInterval(double probability)
      Returns the equal-tail interval containing the requested probability.

    • random

      public double random(RejectionEnvelope envelope, int maxAttempts)
      Draws one value using an explicit rejection envelope.