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
readis True, it is initalized from a Json file with namefilenamethat was created from a MonteCarloTrajectory object before byMonteCarloTrajectory.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_factorandboltzmann_constant. Reading new JSON obtains these inputs fromsampling_info. For older files missing energy_factor, the user must declare it explicitly.metadataholds 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_nameafter 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_funccan be used to calculate the average of one property or several properties. The functionaverage_funchas 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. Withprop_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
prophas the valuevalue.
- get_properties(prop)¶
Return the property
propfrom all entries in the trajectory as array.
- get_property(nid, prop)¶
Return property of entry at index
nidin trajectory.
- get_sampling_step_entry(nid)¶
Return the entry, e.g. the dictionary stored at index
nidin 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
nidin 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
nidin 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. Iffilenameis 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. Iffilenameis not defined, it uses trajectory file name defined in the initialization of MonteCarloTrajectory object.