Symmetric Bloch Density Matrix Quantum Monte Carlo

class pydmqmc.methods.SymmetricBlochDMQMC(system, rng_seed=None, parallel=False)

Bases: DensityMatrixQMC

Density matrix quantum Monte Carlo using the assymetric Bloch equation.

Density matrix quantum Monte Carlo propagates an ensemble of stochastic psi particles (psips). Each psip carries a weight and occupies a specific (i,j) site in the density matrix. During propagation, psips spawn, die, or change weight based on Hamiltonian matrix elements, implementing a Monte Carlo sampling of the density matrix evolution.

In this forumulation, the density matrix starts at an inverse temperature \(\beta = 0\) and is evolved towards the target \(\beta\) according to the symmetrized Bloch equation:

\[d\hat{\rho} / d\beta = -1/2(\hat{H} \hat{rho} + \hat{rho} \hat{H})\]

where \(\hat{\rho}(\beta) = \exp(-\beta \hat{H})\) is the unnormalized thermal density matrix and \(\hat{H}\) is the Hamiltonian operator [1].

Parameters:

systemSystem object

The predefined System to run the model with.

rng_seedint or array_like of ints, optional

Seed or sequence of seeds for the psuedo random number generator. See numpy.random.default_rng()

parallelbool, default False

Whether to use MPI to parallelize the calculation.

Attributes

density_matrix	Density matrix.
final_beta	Target inverse temperature.
is_reporter	Whether the current process is the designated reporter.
parallel	Whether this method is set up to run in parallel.
parallel_is_parent	Whether the current processor is the root if running in parallel.
parallel_rank	Rank of the current processor if running in parallel.
parallel_size	Number of processors if running in parallel.
ran_calculation	Whether or not the calculation has been run.
report	List of dictionaries with report values.
report_requirements	Dictionary of fulfilled requirements for each report value.
report_values	The list of values to be reported throughout the calculation.
system	The System object to which this method is applied.

Methods

do_report(itr_var_name, itr_var_value[, quiet])	Store information about the current iteration in self.report.
parse_method([method])	Parse the supplied string to return the corresponding function.
reset_rng([rng_seed])	Create a new psuedo-random number generator with the given seed.
run(dbeta, cycles_per_shift, shift_dampening)	Run a Density Matrix Quantum Monte Carlo realization.
save_data(basename[, matrix_filetype, ...])	Save the final density matrix and iteration report to file.
setup(final_beta[, initialization, ...])	Specify conditions for the DMQMC realization.

References

[1]

N. S. Blunt, et al., “Density-matrix quantum Monte Carlo method,” Physical Review B, 2014, 89, 245124

do_report(itr_var_name, itr_var_value, quiet=False)

Store information about the current iteration in self.report.

The iteration variable (that is, the variable being monotonically changed as the iteration progresses) must be supplied to provide context about the data being stored.

Only one process (the root, if in parallel) will actually execute this function.

Parameters:

itr_var_namestr

Name of the iteration variable as it should be recorded.

itr_var_valuefloat

Current value of the iteration variable.

quietbool, default False

Silence printing the current report. Report will still be saved internally.

parse_method(method='euler')

Parse the supplied string to return the corresponding function.

Expected call signature for each method is (func, x, y, dy) where func(x, y) = dx/dy.

Supported methods are:

• Forward Euler (euler)

• 4th Order Runge Kutta (rk4)

Parameters:

method{“euler”, “rk4”}

Desired integration method.

Returns:

callable

The associated function from pydmqmc.utils.integrators

reset_rng(rng_seed=None)

Create a new psuedo-random number generator with the given seed.

If running in parallel, each processor will have a unique seed based on the supplied rng_seed.

Parameters:

rng_seedint or array_like of ints, optional

Seed or sequence of seeds for the psuedo-random number generator. See numpy.random.default_rng(). If using MPI parallelization, each processor will have a unique seed based on this value.

run(dbeta, cycles_per_shift, shift_dampening, shift_by_rows=False, spawn_cutoff=0.01, n_add=None, ilevel=None, update_method='euler', quiet=False)

Run a Density Matrix Quantum Monte Carlo realization.

If a site (i,j) has a absolute psip weight less than one, it is stochastically rounded. The Hamiltonian is periodically shifted in order to stabilize the psip population.

Parameters:

dbetafloat

Size of a single update step in inverse temperature \(\beta\).

cycles_per_shiftint

Number of updates to \(\beta\) made before updating the Hamiltonian shift.

shift_dampeningfloat

Affects how much the Hamiltonian shift varies as it updates every cycles_per_shift steps.

shift_by_rowsbool, default false

If True, calculate a shift for each row of the Hamiltonian. If False, calculate one shift for the entire Hamiltonian.

spawn_cutofffloat, default 0.01

Only accumulate psips if the change in a density matrix site \(|\partial p_{ik}| > \mathtt{spawn\_cutoff}\).

n_addfloat, default None

If not None, utilize the initiator approximation and only allow spawning from sites \(p_{ij}\) to empty sites \(p_{ik}\) if \(|p_{ij}| > \mathtt{n_add}\).

ilevelint, default None

If not None, utilize the initiator level approximation, allowing sites \(p_{ij}\) to spawn if the difference in number of excitations between \(i\) and \(j\) is less than ilevel. Requires the system’s excitation_matrix to be defineable if \(\texttt{ilevel} > 0\).

update_methodstr, default “euler”

One of the supported update methods from pydmqmc.methods.Iterative.parse_method()

quietboolean, default False

Silence printing the iteration report as the simulation runs.

Notes

The shift update follows Equation 16 in Blunt et al. 2014 [1]. For more about the various approximations available, see Psip Spawning Control.

References

[1]

N. S. Blunt, et al., “Density-matrix quantum Monte Carlo method,” Physical Review B, 89:245124, 2014

save_data(basename, matrix_filetype='csv', report_filetype='csv', pickle_protocol=None)

Save the final density matrix and iteration report to file.

The basename and filetype parameters will be used to construct filenames for all of the data written to file. For example, if basename is “test_run” and the matrix_ and report_filetype are both “csv”, the density matrix will be saved to “test_run_density_matrix.csv” and the iteration report will be saved to “test_run_report.csv”.

Parameters:

basenamestr

Base name used to construct the filenames for the density matrix and iteration report

matrix_filetypestr, default “csv”

File type (aka extension) with which to save the density matrix. Supported types are:

• “csv” : comma-separated value file

• “npy” : NumPy binary file

• “pkl” : Python pickle file

• “txt” : text file (space-delimited)

report_filetypestr, default “csv”

File type (aka extension) with which to save the report. Supported types are:

• “csv” : comma-separated value file

• “txt” : text file (space-delimited)

• “pkl” : pickle file

pickle_protocolunt, optional

Protocol version to use if either filetype is “pkl”. If none, uses pickle’s default.

setup(final_beta, initialization='deterministic', n_particles=1, fixed_diagonal=None, report_quants=['trace', 'energy expectation'])

Specify conditions for the DMQMC realization.

This setup includes the initial density matrix and a data structure for reporting user-supplied quantities every iteration.

Parameters:

final_betafloat

Target inverse temperature expressed as \(\beta = 1 / (k_\mathrm{B} T)\).

initializationstr, default “deterministic”

Initialization method for the density matrix. See Notes for more. Must be one of:

• deterministic

• random-uniform

• fixed

n_particlesint, default 1

The initial number of psip particles that should be present in the density matrix. Only used with the “deterministic” method.

fixed_diagonalarray_like, optional

Directly defined the diagonal of the density matrix when used with the “fixed” initialization method. The length of diag must be the same as the number of determinants in the system.

report_quantslist, optional

List of quantities to periodically report while performing the calculation. Each item must be recognized by the report_registry. The iteration variable \(beta\) will automatically be included.

Notes

deterministic:

Rows initalized with a weight of 1 on the diagonal elements. This works out to be just the identity matrix and is the canonical starting point for DMQMC.

random-uniform:

Randomly selects diagonal determinants and adds a weight of 1 to that determinant. This can happen multiple times. This is how HANDE initializes the density matrix.

fixed:

Takes the optional parameter fixed_diagonal which is used as the diagonal of the density matrix.

property density_matrix

Density matrix.

property final_beta

Target inverse temperature.

property is_reporter

Whether the current process is the designated reporter.

This process creates the iteration report and writes it to both stdout and to file. If running in serial, the current process is always designated as the reporter.

property parallel

Whether this method is set up to run in parallel.

property parallel_is_parent

Whether the current processor is the root if running in parallel.

property parallel_rank

Rank of the current processor if running in parallel.

property parallel_size

Number of processors if running in parallel.

property ran_calculation

Whether or not the calculation has been run.

property report

List of dictionaries with report values.

property report_requirements

Dictionary of fulfilled requirements for each report value.

property report_values

The list of values to be reported throughout the calculation.

property system

The System object to which this method is applied.