qemcmc.model.constraint_model

Classes

ConstraintModel

A subclass of EnergyModel that incorporates a constraint function to define valid configurations.

Module Contents

class qemcmc.model.constraint_model.ConstraintModel(n: int, constraint_couplings: list[numpy.ndarray], constraint_signs: list[float], couplings: list[numpy.ndarray], constraint_func: Callable[[str], bool], **kwargs)

Bases: qemcmc.model.energy_model.EnergyModel

A subclass of EnergyModel that incorporates a constraint function to define valid configurations.

The constraint function takes a state as input and returns True if the state is valid (satisfies the constraint) and False otherwise. The energy of invalid states is set to infinity, effectively excluding them from the Boltzmann distribution.

Parameters:

• n (int) – Number of spins in the model.

• constraint_couplings (list[np.ndarray]) – List of coupling tensors (numpy arrays) defining the constraint.

• constraint_signs (list[float]) – Sign convention(s) for the constraint couplings.

• couplings (list[np.ndarray]) – List of coupling tensors (numpy arrays) defining the energy function.

• constraint_func (Callable[[str], bool]) – A function that takes a state (string representation of spin configuration) and returns True if the state satisfies the constraint, and False otherwise.

• name (str, optional) – Optional label for the model (used in plotting / logging).

• cost_function_signs (list[float], optional) – Sign convention(s) used by downstream components (e.g. proposal/acceptance conventions).

• model_type (str, optional) – Type of model, either ‘ising’ or ‘binary’. This determines how the binary states are interpreted and how the energy is calculated. ‘ising’ models use spin values {-1, +1}, while ‘binary’ models use binary values {0, 1}.

Notes

• The energy of any state that does not satisfy the constraint is set to infinity, which means such states will have zero probability in the Boltzmann distribution.

• This class can be used to model systems with hard constraints on the configurations, such as certain combinatorial optimization problems or physical systems with forbidden states.

constraint_func

get_initial_states

Generates a list of random initial states.

Parameters:

num_initial_states – The number of initial states to generate.

Returns:

A list of random initial states.

Return type:

list

constraint_couplings

constraint_signs

constraint_coupling_alphas

normalised_couplings

total_couplings

get_initial_states_constraint(num_initial_states: int)

Generates a list of random initial states that satisfy the constraint function.

Parameters:

num_initial_states – The number of initial states to generate.

Returns:

A list of random initial states that are valid according to the constraint.

Return type:

list

get_constraint_energy(state: str) → float

Calculate the energy contribution from the constraint couplings for a given state.

Parameters:

state (str) – The state for which to calculate the constraint energy.

Returns:

The energy contribution from the constraint couplings for the given state.

Return type:

float

get_total_energy(state: str) → float

Calculate the total energy of a given state, including both the regular energy and the constraint energy.

Parameters:

state (str) – The state for which to calculate the total energy.

Returns:

The total energy of the given state, including contributions from both the regular couplings and the constraint couplings.

Return type:

float