.. _physics-posteriorSampleState: Posterior Sampling State ======================== Class providing the state vector during Bayesian posterior sampling simulations---the current position of a Markov chain in parameter space, together with its chain index, step count, and parameter count. Implementations store and retrieve the parameter vector (via ``get``/``set``), advance the step counter, and optionally maintain a history of chain positions for convergence diagnostics. The state is updated at each MCMC step and queried by the likelihood function to evaluate the model at the proposed parameter values. **Default implementation:** ``posteriorSampleStateSimple`` Methods ------- ``parameterCountSet`` → ``void`` Set the number of active parameters that this state vector will track, allocating internal storage for the parameter vector of the given dimension. * ``integer, intent(in ) :: parameterCount`` ``chainIndex`` → ``integer`` Return the integer index (0-based) of the Markov chain that owns this state object, used to identify chains in multi-chain posterior sampling algorithms. ``chainIndexSet`` → ``void`` Assign the integer chain index to this state object, identifying which Markov chain it belongs to in a multi-chain ensemble sampler. * ``integer, intent(in ) :: chainIndex`` ``count`` → ``integer`` Returns the total number of sampling steps that have been taken since the state was last reset, used for logging and convergence diagnostics. ``dimension`` → ``integer`` Returns the number of active parameters (dimension of the state vector) for this sampling state, equal to the value previously set by ``parameterCountSet``. ``reset`` → ``void`` Reset the state object to its initial condition by zeroing the step counter and clearing any accumulated history, in preparation for a new sampling run. ``get`` → ``double precision, dimension(self%parameterCount)`` Return the current parameter vector representing the position of this chain in the model parameter space at the most recently accepted sampling step. ``update`` → ``void`` Advance the state to the new parameter vector ``stateNew``, optionally logging it to the chain history; ``isConverged`` and ``outlierMask`` are used to track whether post-convergence steps should be recorded. * ``double precision, intent(in ), dimension(:) :: stateNew`` * ``logical , intent(in ) :: logState`` * ``logical , intent(in ) :: isConverged`` * ``logical , intent(in ), dimension(:), optional :: outlierMask`` ``mean`` → ``double precision, dimension(self%parameterCount)`` Return the mean parameter vector computed over all stored steps in the chain history, providing a point estimate of the posterior mode or mean. ``variance`` → ``double precision, dimension(self%parameterCount)`` Return the per-parameter variance computed over all stored steps in the chain history, providing a measure of posterior width for each model parameter. ``acceptanceRate`` → ``double precision`` Return the fraction of proposed moves that were accepted over the recent history of this chain, used to monitor and adaptively tune proposal distributions. ``restore`` → ``void`` Replay a previously recorded state vector into the state history one step at a time, used when resuming a sampling run from a saved log file; ``first`` signals the start of the restoration sequence. * ``double precision, intent(in ), dimension(:) :: stateVector`` * ``logical , intent(in ) :: first`` .. _physics-posteriorSampleStateCorrelation: ``posteriorSampleStateCorrelation`` ----------------------------------- An extension of the ``history`` state, this class also computes and stores the correlation length in each parameter (which is taken to be the median correlation length over all non-outlier chains). **Methods** * ``correlationLength`` — Return the current correlation length in the chains. * ``correlationLengthCompute`` — Compute correlation lengths in the chains. * ``postConvergenceCorrelationCount`` — Return the number of post-convergence correlation lengths that have accrued. **Parameters** * ``[acceptedStateCount]`` (integer; default ``100``) — The number of states to use in acceptance rate statistics. .. _physics-posteriorSampleStateHistory: ``posteriorSampleStateHistory`` ------------------------------- An extension of the ``simple`` state, this class also records the mean and variance of each parameter over the history of the simulation. **Methods** * ``operator(+)`` — Addition operator. * ``operator(-)`` — Subtraction operator. * ``operator(/)`` — Division operator. * ``operator(*)`` — Multiplication operator. * ``isZero`` — Returns true if the history is entirely zero. * ``create`` — Creates a history object with a specified range of times. * ``builder`` — Build a history object from an XML definition. * ``dump`` — Dump a history object. * ``dumpRaw`` — Dump a history object in binary. * ``readRaw`` — Read a history object in binary. * ``clone`` — Clone a history object. * ``destroy`` — Destroys a history object. * ``trim`` — Removes any times in a history which have become outdated. * ``trimForward`` — Removes any times in a history *after* the given time. Optionally returns a history object with the removed history. * ``increment`` — Adds two histories, possibly with different time series. * ``interpolatedIncrement`` — Adds two histories, possibly with different time series, by interpolating the second onto the times of the first and adding the interpolated values. * ``extend`` — Extends the time range of a history to encompass the specified limits. * ``reset`` — Resets all entries in a history to zero. * ``setToUnity`` — Set all entries in a history to unity. * ``exists`` — Returns true if the given history has been created. * ``timeSteps`` — Returns an array with the timesteps (i.e. the intervals between successive times) in the given history. * ``serializeCount`` — Return a count of the number of properties in a serialized history object. * ``serialize`` — Serialize a history object to an array. * ``deserialize`` — Deserialize a history object from an array. * ``append`` — Append a history or single instant onto the end of a history. * ``nonStaticSizeOf`` — Returns the size of any non-static components of the type. * ``create`` — Creates a history object with a specified range of times. * ``builder`` — Build a history object from an XML definition. * ``dump`` — Dump a history object. * ``dumpRaw`` — Dump a history object in binary. * ``readRaw`` — Read a history object in binary. * ``clone`` — Clone a history object. * ``destroy`` — Destroys a history object. * ``trim`` — Removes any times in a history which have become outdated. * ``trimForward`` — Removes any times in a history *after* the given time. Optionally returns a history object with the removed history. * ``reset`` — Resets all entries in a history to zero. * ``exists`` — Returns true if the given history has been created. * ``append`` — Append a history or single instant onto the end of a history. * ``nonStaticSizeOf`` — Returns the size of any non-static components of the type. **Parameters** * ``[acceptedStateCount]`` (integer; default ``100``) — The number of states to use in acceptance rate statistics. .. _physics-posteriorSampleStateSimple: ``posteriorSampleStateSimple`` ------------------------------ This class stores the current state but makes no attempt to record a history of the state and so cannot provide measures of the mean or variance of state over the simulation history. It does, however, maintain a running average of the state acceptance rate. The number of steps over which the acceptance rate should be computed is specified by the ``acceptedStateCount``. **(Default implementation)** **Methods** * ``calculationReset`` — Reset memoized calculations. **Parameters** * ``[acceptedStateCount]`` (integer; default ``100``) — The number of states to use in acceptance rate statistics.