Interaction Picture Density Matrix Quantum Monte Carlo

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

Bases: DensityMatrixQMC

Interaction-picture density matrix quantum Monte Carlo.

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.

This formulation take place in the interaction picture.

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()

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 an IP-DMQMC realization.
save_data(basename[, matrix_filetype, ...])	Save the final density matrix and iteration report to file.
setup(final_beta[, initialization, ...])	Set parameters for each of the realizations.

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 an IP-DMQMC realization.

For consistency, uses the value of final_beta set with setup(), even if defined_thermal_weights were supplied.

TODO: What are psips? Initiator & free level approximations? Comment on rounding below |p_ij| > 1.0

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, 24, 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, gc_spawn_cutoff=0.01, defined_thermal_weights=None, fixed_diagonal=None, report_quants=['trace', 'energy expectation'])

Set parameters for each of the realizations.

Parameters:

final_betafloat

Target inverse temperature expressed as \(\beta = 1 / (k_\mathrm{B} T)\). Ignored if defined_thermal_weights is not None.

initializationstr, default “deterministic”

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

• deterministic

• random-uniform

• random-thermal

• random-grand-canonical

• fixed

n_particlesint, default 1

The initial number of psip particles that should be present in the density matrix. Used with the “deterministic”, “random-thermal”, and “random-grand-canonical” methods. Note that for “random-grand-canonical”, n_particles specifies a target minimum number of particles; the actual number of particles in the density matrix may be slightly larger.

gc_spawn_cutofffloat, default None

Used with “random-grand-canonical” initialization method and sets the spawn cutoff for sampling the grand canoncial density matrix. If the initialization method is anything other than “random-grand-canonical,” this parameter is ignored.

defined_thermal_weightsarray_like, optional

Supply pre-defined thermal weights instead of using the auto-generated weights. Useful for, e.g., supplying FCI weights.

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 initialized with the thermal Hartree-Fock weights on the diagonal elements. The canonical starting point for IP-DMQMC.

random-uniform:

Uniformly selects random diagonal determinants and initalizes that row with a weight proportional to the thermal weight from FCI Hamiltonian.

random-thermal:

Selects random rows based on probabilities proportional to the thermal weight of the FCI Hamiltonian diagonal elements. Then occupies that determinant with 1 walker.

random-grand-canonical:

Use knowledge of the grand canonical density matrix correspdongind to the non-interacting Hamiltonian operator \(\hat{H}^0\) to set the initial density matrix. See [1] for more.

fixed:

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

References

[1]

Fionne D. Malone, et. al., “Interaction picture density matrix quantum Monte Carlo,” Journal of Chemical Physics, 143(4):044116, 2015

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.