odatse.algorithm.pamc module

class odatse.algorithm.pamc.Algorithm(info: Info, runner: Runner = None, run_mode: str = 'initial')

Bases: AlgorithmBase

Population Annealing Monte Carlo (PAMC) Algorithm Implementation.

PAMC is an advanced Monte Carlo method that combines features of simulated annealing and population-based methods. It maintains a population of walkers that evolves through a sequence of temperatures, using both Monte Carlo updates and resampling.

Key Features:

• Maintains a population of walkers that evolves through temperature steps

• Uses importance sampling with weight-based resampling

• Supports both fixed and variable population sizes

• Calculates free energy differences between temperature steps

• Provides error estimates through population statistics

Algorithm Flow:

1. Initialize walker population at highest temperature

2. For each temperature step:

1. Perform Monte Carlo updates at current temperature

2. Calculate weights for next temperature

3. Resample population based on weights

4. Update statistical estimates

3. Track best solutions and maintain system statistics

x

Current configurations for all walkers

Type:

np.ndarray

logweights

Log of importance weights for each walker

Type:

np.ndarray

fx

Current energy/objective values

Type:

np.ndarray

nreplicas

Number of replicas at each temperature

Type:

np.ndarray

betas

Inverse temperatures (β = 1/T)

Type:

np.ndarray

Tindex

Current temperature index

Type:

int

Fmeans

Mean free energy at each temperature

Type:

np.ndarray

Ferrs

Free energy error estimates

Type:

np.ndarray

walker_ancestors

Tracks genealogy of walkers for analysis

Type:

np.ndarray

Initialize the Algorithm class.

Parameters:

• info (odatse.Info) – Information object containing algorithm parameters.

• runner (odatse.Runner, optional) – Runner object for executing the algorithm, by default None.

• run_mode (str, optional) – Mode in which to run the algorithm, by default “initial”.

__init__(info: Info, runner: Runner = None, run_mode: str = 'initial') → None

Initialize the Algorithm class.

Parameters:

• info (odatse.Info) – Information object containing algorithm parameters.

• runner (odatse.Runner, optional) – Runner object for executing the algorithm, by default None.

• run_mode (str, optional) – Mode in which to run the algorithm, by default “initial”.

_calc_participation_ratio() → float

Calculate the participation ratio of the current walker population.

The participation ratio is a measure of the effective sample size and indicates how evenly distributed the weights are among walkers. It is calculated as (sum(w))²/sum(w²), where w are the normalized weights.

A value close to the total number of walkers indicates well-distributed weights, while a small value indicates that only a few walkers dominate the population.

To avoid numerical issues with large log-weights, we normalize by subtracting the maximum log-weight before exponentiation.

Parameters:

None – Uses the current state of self.logweights

Returns:

The participation ratio, a value between 1 and the total number of walkers

Return type:

float

Notes

In parallel execution, this method aggregates weights across all processes to calculate the global participation ratio.

_find_scheduling(info_pamc) → int

Determine the temperature schedule and number of steps.

The schedule can be specified in three ways:

1. Total steps and steps per temperature

2. Total steps and number of temperatures

3. Steps per temperature and number of temperatures

The method ensures even distribution of computational effort across temperature steps while respecting the specified constraints.

Parameters:

info_pamc (dict) –

Configuration dictionary containing:

• numsteps: Total number of Monte Carlo steps

• numsteps_annealing: Steps per temperature

• Tnum: Number of temperature points

Returns:

Number of temperature steps in the schedule

Return type:

int

Raises:

odatse.exception.InputError – If the scheduling parameters are inconsistent

_gather_information(numT: int = None) → Dict[str, ndarray]

Collect and organize statistical information across all processes.

Gathers data needed for:

1. Free energy calculations

2. Error estimation

3. Population statistics

4. Acceptance rate monitoring

Parameters:

numT (int, optional) – Number of temperature steps to gather data for

Returns:

Contains:

• fxs: Energy values for all walkers

• logweights: Log of importance weights

• ns: Number of walkers per process

• ancestors: Genealogical tracking data

• acceptance ratio: MC acceptance rates

Return type:

Dict[str, np.ndarray]

_initialize() → None

Initialize the Monte Carlo simulation state.

For continuous problems:

• Uses domain.initialize to generate valid initial positions

• Respects any additional limitations from the runner

For discrete problems:

• Randomly assigns walkers to valid nodes

• Maps node indices to actual coordinate positions

Also initializes:

• Objective function values (fx) to zero

• Best solution tracking variables

• Acceptance counters for monitoring convergence

_load_state(filename, mode='resume', restore_rng=True)

Load the saved state of the algorithm from a file.

Parameters:

• filename (str) – The name of the file from which the state will be loaded.

• mode (str, optional) – The mode in which to load the state. Can be “resume” or “continue”, by default “resume”.

• restore_rng (bool, optional) – Whether to restore the random number generator state, by default True.

_post() → Dict

Post-processing after the algorithm execution.

This method consolidates the results from different temperature steps into single files for ‘result’ and ‘trial’. It also gathers the best results from all processes and writes them to ‘best_result.txt’.

_prepare() → None

Prepare the algorithm for execution.

This method initializes the timers for the ‘submit’ and ‘resampling’ phases of the algorithm run.

_resample() → None

Perform population resampling between temperature steps.

This is a key component of PAMC that:

1. Gathers current population statistics

2. Calculates importance weights for the temperature change

3. Resamples walkers based on their weights

4. Updates population statistics and free energy estimates

The resampling can be done in two modes:

• Fixed: Maintains constant population size

• Varied: Allows population size to fluctuate based on weights

Implementation Details:

• Uses log-weights to prevent numerical overflow

• Maintains walker genealogy for analysis

• Updates free energy estimates using resampling data

• Handles MPI communication for parallel execution

_resample_fixed(weights: ndarray) → None

Perform resampling with fixed weights.

This method resamples the walkers based on the provided weights and updates the state of the algorithm accordingly.

Parameters:

weights (np.ndarray) – Array of weights for resampling.

_resample_varied(weights: ndarray, offset: int) → None

Resample population allowing size variation.

Uses Poisson resampling:

1. Calculates expected number of copies from weights

2. Samples actual copies using Poisson distribution

3. Creates new population with variable size

4. Updates all walker properties

Parameters:

• weights (np.ndarray) – Importance weights for resampling

• offset (int) – Process-specific offset in global population

_run() → None

Abstract method to be implemented by subclasses for running steps.

_save_state(filename) → None

Save the current state of the algorithm to a file.

Parameters:

filename (str) – The name of the file where the state will be saved.

_save_stats(info: Dict[str, ndarray]) → None

Calculate and save statistical measures from the simulation.

Performs:

1. Free energy calculations using weighted averages

2. Error estimation using jackknife resampling

3. Population size tracking

4. Acceptance rate monitoring

5. Partition function estimation

Uses bias-corrected jackknife for reliable error estimates of weighted averages in the presence of correlations.

Parameters:

info (Dict[str, np.ndarray]) –

Dictionary containing the following keys:

• fxs: Objective function of each walker over all processes.

• logweights: Logarithm of weights.

• ns: Number of walkers in each process.

• ancestors: Ancestor (origin) of each walker.

• acceptance ratio: Acceptance ratio for each temperature.