Utilities

utilities

Collection of utility functions for MTMLDA runs.

This utility functions are not part of the MTMLDA core library, as they are utilized only for the run wrapper and specific applications. They are mainly concerned with the execution of parallel chains, along with loading and saving states of the sampler for reinitialization.

Functions:

Name	Description
distribute_rng_seeds_to_processes	Distribute RNG seeds to parallel processes, based on their id
append_string_to_path	Extend a Path object with a string for its name
load_chain	Load MCMC chain data from npy file
save_chain	Save MCMC chain array to npy file
load_pickle	Load a pickled object into memory
save_pickle	Save a generic object into pickle
request_umbridge_server	Request UM-Bridge server with fail-save for long response times

mtmlda.utilities.distribute_rng_seeds_to_processes

distribute_rng_seeds_to_processes(seeds: list | int, process_id: int) -> int

Distribute and optionally modify seeds for different parallel processes.

This is a generic function that distributes RNG seeds to parallel processes when running MCMC with multiple independent chains. It can be used in two different ways. If the seeds are specified as a list, each process will receive the seed at the corresponding index. If the seeds are specified as a single value, each process will receive a seed that is the product of that value and the process ID.

Parameters:

Name	Type	Description	Default
seeds	Union[list, int]	RNG seeds to distribute to processes, list or single value	required
process_id	int	Integer ID of the calling process	required

Returns:

Name	Type	Description
Real	int	RNG seed for the calling process

mtmlda.utilities.append_string_to_path

append_string_to_path(path: Path, string: int) -> Path

Extend a Path object with a file name extension provided as a string.

The new path object's name is extended by "_string". This routine is used to create process- specific file names by appending the ID of the calling process. Such a convention is also assumed when loading files.

Parameters:

Name	Type	Description	Default
path	Path	Path object	required
string	int	String extending the file name	required

Returns:

Name	Type	Description
Path	Path	New path, name extended by "_string"

mtmlda.utilities.get_specific_file_type

get_specific_file_type(directory: Path, file_type: str) -> list[str]

Get all files of a specific type in a directory.

mtmlda.utilities.load_chain

load_chain(process_id: int, load_path: Path) -> None

Load MCMC chain data from npy file.

The provided file path is extended by the process ID via the append_string_to_path function. Clearly, this method only works if it is called by the exact same number of chains that have been saved before.

Parameters:

Name	Type	Description	Default
process_id	int	ID of the calling process	required
load_path	Path	Generic path to find chain files in	required

Raises:

Type	Description
FileNotFoundError	Checks if the chain file exists

Returns:

Type	Description
None	np.ndarray: MCMC chain

mtmlda.utilities.save_chain

save_chain(process_id: int, save_path: Path, mcmc_trace: list[np.ndarray], exist_ok: bool) -> None

Save MCMC chain array to npy file.

The save path is process-specific through the append_string_to_path function.

Parameters:

Name	Type	Description	Default
process_id	int	ID of the calling process	required
save_path	Path	Generic path to save chain files to	required
mcmc_trace	list[np.ndarray]	MCMC chain array to save	required
exist_ok	bool	Choose if existing file should be overwritten	required

mtmlda.utilities.load_pickle

load_pickle(process_id: int, load_path: Path) -> Any

Load a pickled object into memory.

The provided file path is extended by the process ID via the append_string_to_path function. This method only works if it is called by the exact same number of processes that have been used for saving. The method is generic, and used for loading rng states and Markov tree nodes.

Parameters:

Name	Type	Description	Default
process_id	int	ID of the calling process	required
load_path	Path	Generic load path	required

Raises:

Type	Description
FileNotFoundError	Checks if the specified file exists

Returns:

Name	Type	Description
Any	Any	Loaded object

mtmlda.utilities.save_pickle

save_pickle(process_id: int, save_path: Path, save_object: Any, exist_ok: bool) -> None

Save a generic object into pickle.

The save path is process-specific through the append_string_to_path function. The method is generic, and used for saving rng states and Markov tree nodes.

Parameters:

Name	Type	Description	Default
process_id	int	ID of the calling process	required
save_path	Path	Generic save path	required
save_object	Any	Object to save	required
exist_ok	bool	Choose if existing object should be overwritten	required

mtmlda.utilities.request_umbridge_server

request_umbridge_server(process_id: int, address: str, name: str) -> ub.HTTPModel

Request UM-Bridge model server with fail-save for long response times.

The function tries to connect to an UM-Bridge server at the provided address and name. It is a simple wrapper to the 'HTTPModel' class constructor. It repeatedly tries to connect to the server until it is available.

Parameters:

Name	Type	Description	Default
process_id	int	ID of the calling process	required
address	str	Address of the UM-Bridge server to call	required
name	str	Name of the UM-Bridge server to call	required

Returns:

Type	Description
ub.HTTPModel	ub.HTTPModel: UM-Bridge server object