The MonteCarloTrajectory class

This class embodies the trajectories generated by the Metropolis simulations in a Monte Carlo run at finite temperature.

Initialization and methods

class clusterx.thermodynamics.monte_carlo.MonteCarloTrajectory(scell=None, filename='trajectory.json', read=False, *, energy_factor=None, boltzmann_constant=None, temperature=None, no_of_sampling_steps=None, models=None, target_rate=None, save_nsteps=10, reduce_structure=False, ensemble=None, metadata=None)

MonteCarloTrajectory class

Objects of this class are used to store and access information of the trajectory generated from a Monte Carlo sampling performed with the MonteCarlo class.

It is initialized with the SuperCell object. Alternative: If read is True, it is initalized from a Json file with name filename that was created from a MonteCarloTrajectory object before by MonteCarloTrajectory.serialize().

Parameters:
scellSuperCell

Super cell in which the sampling is performed.

filenamestr, default trajectory.json

The trajectoy can be stored in a json file with the path given by filename.

readbool, default False

If True, the trajectory is read from the Json file filename.

Notes

New trajectories require an explicit scalar energy_factor and boltzmann_constant. Reading new JSON obtains these inputs from sampling_info. For older files missing energy_factor, the user must declare it explicitly. metadata holds optional descriptive information; unknown constructor keywords are errors.

add_step(step: int, energy: float, indices_list: list[int], new_sigmas: list[int], sigmas: list[int] | None = None, key_value_pairs: dict = {})

Add entry of the structure visited in the sampling to the trajectory.

calculate_average_property(prop_name='U', no_of_equilibration_steps=0, average_func=None, props_list=None, **kwargs)

Average a complete accepted-move history (sample with serialize=True).

Get averaged property of property with name prop_name after discarding at the start a given number of equilibration steps. The average can only be obtained from a property that was already calculated before, e.g. by MonteCarlo.Trajectory.calculate_properties(…).

Alternatively, an external function average_func can be used to calculate the average of one property or several properties. The function average_func has as arguments an array containing the properties used for the average at each sampling index, i.e. [[prob1_1,prop1_2,…,prop1_N], [prop2_1,prop2_2,…,prop2_N],…], and optional keyword arguments. With prop_list, the property names of prob1, prop_2, … are defined.

Parameters:
prop_namestr, default U

Name of property that is averaged. If U, return mean TOTAL supercell energy after applying energy_factor. Reduced MC retains its relative initial-state energy zero. C_p is the historical name for the TOTAL configurational heat capacity Var(E_total)/(k_B*T**2), in energy per temperature unit. It requires a canonical, fixed-temperature trajectory without target-rate adaptation. It does not include pressure/volume terms and is not normalized per atom or reported in units of k_B.

no_of_equilibration_stepsint

Number of equilibration steps at the start of the Monte-Carlo sampling that are discarded from the average.

average_funcfunction, default None

If not None, the averaged property is obtained by this function. It gets as arguments an array and optional keyword arguments.

**kwargskeyword arguments

Additional arguments for average_func.

calculate_properties(models=[], prop_func=None, prop_name=None, **kwargs)
Calculate the property for all decorations in the trajectory. The property can be

calculated by a Model object or an external function prop_func.

Parameters:
modelslist, default empty list
prop_funcfunction, default None

This function recieves as arguments the Structure object and the dictionary of trajectory entry at step i, and additional keyword arguments given by **kwargs.

prop_namestr, default None

Name of property which is calculated by prop_func.

**kwargskeyworded argument list, arbitrary length

Additional parameters for the function prop_func

get_energies()

Return raw model energies, before energy_factor (relative for reduced MC).

get_energy(nid)

Return the raw model energy of entry nid, before energy_factor.

get_lowest_energy_structure()

Return Structure object with the lowest energy in trajectory.

get_model_total_energies()

Return supercell energies in the user-chosen energy unit; retain any reduced-MC offset.

get_model_total_energy(nid)

Return one supercell energy, retaining the reduced-MC relative zero when used.

get_nid_sampling_step(nstep)

Return entry index at the n-th sampling (nstep) step in trajectory.

get_nids(prop, value)

Return array of integers, that are the indices of the entries in trajectory for which the property prop has the value value.

get_properties(prop)

Return the property prop from all entries in the trajectory as array.

get_property(nid, prop)

Return property of entry at index nid in trajectory.

get_sampling_step_entry(nid)

Return the entry, e.g. the dictionary stored at index nid in trajectory.

get_sampling_step_entry_at_step(nstep)

Return the entry, e.g. the dictionary stored for the n-th samplig step (nstep) in trajectory.

get_sampling_step_no(nid)

Return sampling step number of entry at index nid in trajectory.

get_sampling_step_nos()

Return sampling step numbers of all entries in trajectory as array.

get_structure(nid)

Return structure in form of a Structure object, at index nid in trajectory.

get_structure_at_step(nstep)

Return structure in form of a Structure object, at the n-th sampling step (nstep) in trajectory.

read(filename=None, append=False)

Read trajectory from the Json file with name filename. If filename is not defined, it uses trajectory file name defined in the initialization of the MonteCarloTrajectory.

serialize(filename=None)

Write trajectory to Json file with name filename. If filename is not defined, it uses trajectory file name defined in the initialization of MonteCarloTrajectory object.