Multilevel Sampler

sampling ¶

Main component of the MTMLDA library.

This module implements the actual MTMLDA sampler. It therefore combines the functionalities from the other modules in the package.

Classes:

Name	Description
`SamplerSetupSettings`	Settings for initialization of the MLDASampler.
`SamplerRunSettings`	Settings for conduction of a run with an initialized MLDASampler.
`RNGStates`	Collection of random number generators of different sub-components, for re-initialization of the sampler
`MTMLDASampler`	Main object for thread-parallel MLDA sampling.

mtmlda.core.sampling.mltree_search ¶

Collection of functions for analyzing a Markov tree without modification.

This class is only a namespace for the contained functions, all methods are static. The search functions iterate over an existing Markov tree and find nodes that fulfill certain criteria.

Methods:

Name	Description
`find_max_probability_node`	Find the node with the maximum probability of being reached
`get_same_level_parent`	Find the parent node of the same level as the input node, if it exists
`get_unique_same_subchain_child`	Find the unique child of a node with the same level, if it exists (i.e. if all intermediate MCMC decisions have been carried out)
`check_if_node_is_available_for_decision`	Check if a node is available for an MCMC decision, depending on if its log-posterior and those of "adjacent nodes" have been computed

find_max_probability_node `staticmethod` ¶

find_max_probability_node(root: MTNode) -> MTNode

Find node in the Markov tree with the maximum probability of being needed.

More precisely, the method looks for the node that is most likely to be needed in the progression of the Markov tree. This is the node whose parent has the highest probability of being reached. The method only checks for accept nodes whose log-posterior has not been computed yet.

Parameters:

Name	Type	Description	Default
`root`	`MTNode`	Current root node of the Markov tree	required

Returns:

Name	Type	Description
`MTNode`	`MTNode`	Maximum probable node

get_same_level_parent `staticmethod` ¶

get_same_level_parent(node: MTNode) -> MTNode | None

Find next parent with same level in the MLDA hierarchy.

Parameters:

Name	Type	Description	Default
`node`	`MTNode`	Node to search parent for	required

Returns:

Name	Type	Description
`MTNode`	`MTNode \| None`	Same level parent node, can be None

get_unique_same_level_child `staticmethod` ¶

get_unique_same_level_child(node: MTNode) -> MTNode | None

Get the unique child on the the same level of the MLDA hierarchy.

Uniqueness refers to the path in the Markov tree, meaning that all MCMC decisions between a node and the same level child have to be carried out.

Parameters:

Name	Type	Description	Default
`node`	`MTNode`	Node to get unique child for	required

Returns:

Name	Type	Description
`MTNode`	`MTNode \| None`	Unique same level child, can be None

check_if_node_is_available_for_decision `staticmethod` ¶

check_if_node_is_available_for_decision(node: MTNode) -> tuple[bool, bool, bool]

Check if a node is available for MCMC descicion.

A node has to fulfill some general criteria to be available for an MCMC decision. These are checked with the decision_prerequisites_fulfilled conditional. After that, we distinguish two different cases. On the ground level of the MLDA hierarchy, the node's posterior and its immediate parent's posterior (which also has to be on the ground level) have to be computed. For the second case of a two-level decision, we require four posterior values to be available. Firstly, we need the values for the first and last node of the coarser sub-chain. Secondly, we need the values for the current finer level state and the proposal on that level. The method returns three booleans, indicating if the node is generally available for a decision, if it is a ground level decision, or if it is a two-level decision.

Parameters:

Name	Type	Description	Default
`node`	`MTNode`	Node to check	required

Returns:

Type	Description
`tuple[bool, bool, bool]`	tuple[bool, bool, bool]: Booleans indicating if node is available for decision, and which type of decision

check_if_leaf_is_available_for_computation `staticmethod` ¶

check_if_leaf_is_available_for_computation(root: MTNode) -> bool

Check if a leaf node is ready for computation.

This means that the node has not been visited yet.

Parameters:

Name	Type	Description	Default
`root`	`MTNode`	Root node of the Markov tree	required

Returns:

Name	Type	Description
`bool`	`bool`	If any leaf is available for computation

mtmlda.core.sampling.SamplerSetupSettings `dataclass` ¶

Settings for initialization of the MLDASampler.

Attributes:

Name	Type	Description
`num_levels`	`int`	Number of levels in the MLDA hierarchy.
`subsampling_rates`	`list`	List of sub-chain lengths for each level.
`max_tree_height`	`int`	Maximum height of the tree, purely technical, default is 50.
`underflow_threshold`	`float`	Threshold for underflow of log-posterior values, below posterior probability is treated as zero, default is -1000.
`rng_seed_mltree`	`int`	Seed for the random number generator used in the MLTreeModifier.
`rng_seed_node_init`	`int`	Seed for the random number generator used for initialization of the the first node in the Markov tree.
`mltree_path`	`str`	Path to the directory where the Markov trees are to be exported as dot files. Default is none, meaning that no trees are exported.

mtmlda.core.sampling.SamplerRunSettings `dataclass` ¶

Settings for conduction of a run with an initialized MLDASampler.

Attributes:

Name	Type	Description
`num_samples`	`int`	Number of samples to be generated on the fine level.
`initial_state`	`np.ndarray`	Initial state of the Markov chain.
`initial_node`	`mltree.MTNode`	Initial node of the Markov tree, if not given, the initial state is used to create the first node. Can be used for reinitialization. Default is None.
`num_threads`	`int`	Number of threads to be used for parallel evaluation of posterior evaluation requests. Default is 1.
`print_interval`	`int`	Interval for printing run statistics, default is 1.

mtmlda.core.sampling.RNGStates `dataclass` ¶

Collection of random number generators of different sub-components.

Can be returned for reproducibility of runs.

mtmlda.core.sampling.MTMLDASampler ¶

Main object for parallel MLDA sampling.

the MTMLDASampler is the main component of the MLDA code base. It is a composite object, taking arguments for the logger, a model hierarchy, and accept rate estimator, and a proposal. In addition, it internally initializes an MH Kernel object and everything related to working with Markov trees for prefetching. The run method produces a Markov chain for the fine level posterior by repeatedly looping through a number of steps: 1. Extend the Markov tree by adding new nodes. 2. Launch jobs for evaluating the posterior at the new nodes. 3. Update the tree with the results of the finished jobs. 4. Compute available MCMC decisions. 5. Propagate the chain by accepting or rejecting nodes.

Evaluation calls are implemented via a job handler, which is a wrapper around a ThreadPoolExecutor object.

Methods:

Name	Description
`run`	Main method for running the sampler.
`get_rngs`	Get the random number generators used in the sampler.
`set_rngs`	Set the random number generators used in the sampler.

init ¶

__init__(
    setup_settings: SamplerSetupSettings,
    logger_settings: logging.LoggerSettings,
    models: Sequence[Callable],
    accept_rate_estimator: mcmc.BaseAcceptRateEstimator,
    ground_proposal: mcmc.BaseProposal,
) -> None

Constructor of the MLDA sampler.

The constructor assembles the composite sampler object. Components for which multiple options might be necessary are passed as arguments, while components that are unique are created internally.

Parameters:

Name	Type	Description	Default
`setup_settings`	`SamplerSetupSettings`	Data class with settings for sampler setup	required
`logger_settings`	`logging.LoggerSettings`	Data class with settings for the logger	required
`models`	`Sequence[Callable]`	List of callables resembling the MLDA model hierarchy	required
`accept_rate_estimator`	`mcmc.BaseAcceptRateEstimator`	Accept rate estimator for prefetching	required
`ground_proposal`	`mcmc.BaseProposal`	Proposal object for the ground level MCMC chain	required

run ¶

run(run_settings: SamplerRunSettings) -> list[np.ndarray]

Main run methods for the sampler.

The method takes a data class with run-specific settings. As described in the constructor, it initiates a while loop that continuous until the desired number of fine level samples has been generated. This method is mainly an interface, most of the program logic is implemented in the private sub-methods.

Parameters:

Name	Type	Description	Default
`run_settings`	`SamplerRunSettings`	Settings for the sampler run.	required

Returns:

Type	Description
`list[np.ndarray]`	list[np.ndarray,mltree.MTNode]: Produced Markov chain and the final Markov tree root.

get_rngs ¶

get_rngs() -> RNGStates

Get the random number generators used in the algorithm.

set_rngs ¶

set_rngs(rng_states: RNGStates) -> None

Set the random number generators used in the algorithm.

_init_mltree ¶

_init_mltree(
    initial_state: np.ndarray | None = None, initial_node: mltree.MTNode | None = None
) -> mltree.MTNode

Initialize the Markov tree for prefetching.

The method either takes an initial state or a Markov tree node. In the first case, a new tree is initialized from the state alone. If a node is provided, its log-posterior and random draw is also taken over to the new tree.

Parameters:

Name	Type	Description	Default
`initial_state`	`np.ndarray`	Initial state of the Markov chain.	`None`
`initial_node`	`mltree.MTNode`	Markov tree node to be utilized as initial state.	`None`

Returns:

Type	Description
`mltree.MTNode`	mltree.MTNode: Root of the Markov tree.

_extend_tree_and_launch_jobs ¶

_extend_tree_and_launch_jobs(mltree_root: mltree.MTNode) -> None

Expands the Markov tree and requests evaluation of posterior for new nodes.

The methods uses the MLTreeModifier to expand the Markov tree and requests new evaluations from the JobHandler. Jobs requested correspond to those most likely needed in accordance with the acceptance rate estimates.

Parameters:

Name	Type	Description	Default
`mltree_root`	`mltree.MTNode`	Root of the Markov tree to extend	required

_update_tree_from_finished_jobs ¶

_update_tree_from_finished_jobs(mltree_root: mltree.MTNode) -> None

Get finished jobs from job handler, update Markov tree accordingly.

If a job returns with log-probability lower than the underflow threshold, the corresponding node and its descendants are discarded, since they correspond to states that are impossible to reach. Otherwise, the log-probability is transferred to the node and its descendants are updated accordingly.

Parameters:

Name	Type	Description	Default
`mltree_root`	`mltree.MTNode`	Current Markov tree, only necessary for visualization.	required

_compute_available_mcmc_decisions ¶

_compute_available_mcmc_decisions(mltree_root: mltree.MTNode) -> None

Traverse the Markov tree repeatedly and compute available MCMC decisions.

This includes one-level and two-level decisions. As the tree structure is modified after an MCMC decision, it is completely traversed after each decision. The acceptance rates for each level are updated accordingly.

Parameters:

Name	Type	Description	Default
`mltree_root`	`mltree.MTNode`	Markov tree root to compute decisions from.	required

_propagate_chain ¶

_propagate_chain(
    mcmc_chain: Sequence[np.ndarray], mltree_root: mltree.MTNode
) -> tuple[Sequence[np.ndarray], mltree.MTNode]

Propagate chain from one fine level sample to the next.

Propagation takes place if a unique path is available between the corresponding nodes in the Markov tree. The new sample becomes the root of the Markov tree for the next iteration. The procedure is repeated until no more unique paths can be found.

Parameters:

Name	Type	Description	Default
`mcmc_chain`	`Sequence[np.ndarray]`	List of fine level samples	required
`mltree_root`	`mltree.MTNode`	current Markov tree root	required

Returns:

Type	Description
`tuple[Sequence[np.ndarray], mltree.MTNode]`	tuple[Sequence[np.ndarray], mltree.MTNode]: Updated Markov chain and tree root

_init_statistics ¶

_init_statistics() -> tuple[dict[str, logging.Statistic], dict[str, logging.Statistic]]

Initialize statistics dictionaries.

The MTMLDA logger takes two types of statistics: Run statistics are logged in a table, debug statistics contain more detailed information, logged to a separate file. All statistics are stored in the respective dictionaries with a string handle, a string id for the output, and the format the corresponding value should be printed in.

Returns:

Type	Description
`tuple[dict[str, logging.Statistic], dict[str, logging.Statistic]]`	tuple[dict[str, logging.Statistic], dict[str, logging.Statistic]]: Debug and run statistics

_update_run_statistics ¶

_update_run_statistics(mcmc_chain: list[np.ndarray]) -> dict[str, logging.Statistic]

Update values in the run statistics dictionary.

Parameters:

Name	Type	Description	Default
`mcmc_chain`	`list[np.ndarray]`	Current MCMC chain	required

Returns:

Type	Description
`dict[str, logging.Statistic]`	dict[str, logging.Statistic]: Updated statistics dictionary

_update_debug_statistics ¶

_update_debug_statistics(node: mltree.MTNode) -> dict[str, logging.Statistic]

Update values in the debug statistics dictionary.

Parameters:

Name	Type	Description	Default
`node`	`mltree.MTNode`	Markov tree node to extract debug information from	required

Returns:

Type	Description
`dict[str, logging.Statistic]`	dict[str, logging.Statistic]: Updated statistics dictionary

_log_run_statistics ¶

_log_run_statistics(mcmc_chain: Sequence[np.ndarray]) -> None

Print out run statistics to table.

Only executes if the number of samples is a multiple of the print interval or the last

Parameters:

Name	Type	Description	Default
`mcmc_chain`	`Sequence[np.ndarray]`	current MCMC chain	required

_log_debug_statistics ¶

_log_debug_statistics(info: str, node: mltree.MTNode) -> None

Print out debug statistics to separate file.

Parameters:

Name	Type	Description	Default
`info`	`str`	String name for event to be logged	required
`node`	`mltree.MTNode`	Node to log debug info for	required

_export_debug_tree ¶

_export_debug_tree(root: mltree.MTNode) -> None

Export Markov tree dot file and log event.

Parameters:

Name	Type	Description	Default
`root`	`mltree.MTNode`	Root of the Markov tree to export	required

Multilevel Sampler

sampling ¶

mtmlda.core.sampling.mltree_search ¶

find_max_probability_node staticmethod ¶

get_same_level_parent staticmethod ¶

get_unique_same_level_child staticmethod ¶

check_if_node_is_available_for_decision staticmethod ¶

check_if_leaf_is_available_for_computation staticmethod ¶

mtmlda.core.sampling.SamplerSetupSettings dataclass ¶

mtmlda.core.sampling.SamplerRunSettings dataclass ¶

mtmlda.core.sampling.RNGStates dataclass ¶

mtmlda.core.sampling.MTMLDASampler ¶

__init__ ¶

run ¶

get_rngs ¶

set_rngs ¶

_init_mltree ¶

_extend_tree_and_launch_jobs ¶

_update_tree_from_finished_jobs ¶

_compute_available_mcmc_decisions ¶

_propagate_chain ¶

_init_statistics ¶

_update_run_statistics ¶

_update_debug_statistics ¶

_log_run_statistics ¶

_log_debug_statistics ¶

_export_debug_tree ¶

find_max_probability_node `staticmethod` ¶

get_same_level_parent `staticmethod` ¶

get_unique_same_level_child `staticmethod` ¶

check_if_node_is_available_for_decision `staticmethod` ¶

check_if_leaf_is_available_for_computation `staticmethod` ¶

mtmlda.core.sampling.SamplerSetupSettings `dataclass` ¶

mtmlda.core.sampling.SamplerRunSettings `dataclass` ¶

mtmlda.core.sampling.RNGStates `dataclass` ¶

init ¶