Python Module tools

Module tools.py provides functions to write files for the Fortran backend and run serial simulations from the command line.

last revision 091911-MLW / instead of &end as end of namelist file for consistency with nagfor

tools.write_makefile(settings)

Write out the main file for compiling the fortran library. Return boolean if MPI is used.

Arguments

settingsdict

Key-value pairs for the settings of the compiler. Necessary keys are PY, FC, OFLAGS, OPENMP, BLAS_FLAG, LAPACK_FLAG, ARPACK_FLAG, HDF5_FLAG, LIBFLAGS.

tools.BuildMPSFortLib(Parallel=False, tests=False, track=True)

Make the fortran libraries. The return vector contains the status of make command for serial, parallel, and tests in this order if all are compiled.

Arguments

Parallelboolean, optional

sets flag for openMPI compilation. default to False (serial code without MPI)

testsboolean, optional

Set handling if tests for fortran modules are compiled (True) or not (False). Default to True.

trackboolean, optional

Flag if line numbers are decoded in file make.log (True) or if original output goes to standard out (False). Default to True.

tools.CleanMPSFortLib()

Clean the fortran libraries.

tools.InstallMPSFortLib(INSTALLATION_DIR='/usr/local/bin', Parallel=False)

Install the Fortran libraries, that is copying the build executabels to the installation directory.

Arguments

INSTALLATION_DIRstr, optional

path of the installation directory. default to /usr/local/bin/

Parallelboolean, optional

flag for openMPI installation. If True, MPI-executable is copied as well to the installation directory default to False

tools.InstallMPSCLIUtility(INSTALLATION_DIR='/usr/local/bin')

tools.execute(command, cwd=None)

Execute the given command on the command line.

Arguments

commandlist of strings

List with all parts of the command. Parts seperate by whitespaces form a individual entry in the list.

tools.submit_job(script_name, comp_info)

Submits a job to the cluster.

Arguments

script_name

name of the pbs/slurm script to be submitted.

comp_infodictionary

dictionary with cluster settings, of interest is the key queueing to decide whether pbs or slurm is used.

tools.runMPS(infileList, RunDir=None, Debug=False, customAppl=None)

Run the MPS application with the given list of input files.

Arguments

infileListlist

list of of the main files passed to fortran executable as command line argument.

RunDirstr, optional

Specifies path of the fortran-executable (local or global installation). This is available for default-simulation and custom application. (@Developers: Debugging with valgrind always works with a local installation.) None : if executable available within local folder, use local installation, otherwise assume global installation, default ‘’ (empty string) : for global installation ‘./’ : local installation PATH+’/’ : path to executable ending on slash /. Additional steps may be necessary when using this.

Debugboolean, optional

Developers only: false : run usual simulation, default true : run debugging with valgrind using local installation If the folder MPSFortLib is visible, then line numbers from f90 modules are de-references to the template line numbers. (visible = actual MPSFortLib folder in the present working directory, a symbolic link to MPSFortLib, …)

customApplstr, optional

define custom executable. Global and local installation work as before. Custom applications cannot run with valgrind. default to None (running default executable)

tools.WriteHparams(fileStub, Parameters, IntHparams)

Write out the hamiltonian Parameters to a Fortran-readable file.

Arguments

fileStubstring

basis for the filename extended with HamiParams.dat

Parametersdictionary

keys correspond to values of IntHparams[i] for integers i values are floats for translational invariance models or lists/np.ndarrays for translational variance models.

IntHparamsdictionary

key num defines the number of parameters. Keys (integer) from 0 to num - 1 can be set if the change (no warranty that this is right)

Details

The part written by one call of WriteHparams looks like

1. number of parameters (integer)

2. number of sites (1=translational invariance)

3. floats for coupling

tools.WriteMainFile(p, cmplx_op, hashlist, MainHashList, nqns=0, npns=0, Operators=None, PostProcess=False)

Subprogram to write main files from a parameter dictionary p for a MPS simulation. Intended for internal use only.

Arguments

pdictionary

p contains the parameter settings for the simulation specified through various keys.

cmplx_opboolean

True : at least one operator is complex valued False : all operators are real

hashlistlist of strings

contains a list of hashes to be merged to one single hash identifying the variational/static search of MPS (containing the information about Hamiltonian, the couplings, convergence settings etc …)

MainHashListlist of strings

List contains the hashes of previous main files to check

nqnsinteger, optional

default to 0

npnsinteger, optional

default to 0

Operatorsinstance of OperatorList, optional

default to None

PostProcesslogical, optional

unused, default to False

Details

The file …qnumbers.dat is written during this function.

tools.generate_full_hash(hashlist)

Generate the full hash for a simulation based on a list of hashes.

Arguments

hashlistlist of strings

contains a list of hashes to be merged to one single hash identifying the variational/static search of MPS (containing the information about Hamiltonian, the couplings, convergence settings etc …)

tools.WriteFiles(Parameters, Operators, HamiltonianMPO, PostProcess=False, EDSim=False)

Write out files for use by the Fortran routines.

Arguments

Parameters: single dictionary or list of dictionaries

Arguments in the dictionary are job_ID (mandatory), unique_ID, Write_Directory (optional), Output_Directory (optional) L (system size?, mandatory), verbose, MPSObservables, MPSConvergenceParameters [list incomplete]

Operatorsdictionary

dictionary containing the matrices for the operators. The keys are the names of the operators as string.

HamiltonianMPOinstance of MPO or list of instances of MPO

containing the Hamiltonian. If list, it has to have the same length as the Parameters-list. If Parameters is a list, HamiltonianMPO can still be a single instance of MPO.

PostProcessboolean

function distinguishes between writing files for the fortran simulation (PostProcess=False) and running the postprocessing of an existing data set (PostProcessing=True).

EDSimboolean

Specify that the setup is for an ED simulation. This suppresses writing temporary files similar to PostProcess=True overwriting the PostProcessing flag.

Details

The following keys exist in Parameters:

Key (strings)	Description	opt
L	Integer value specifying the length of the lattice for finite systems and the length of the unit cell for infinite systems	N
job_ID	String specifying a simulation. For batched simulations, 'job_ID' specifies a group of simulations which are distinguished by their 'unique_ID'.	N
simtype	Takes values of 'Finite' or 'Infinite' to toggle between finite and infinite-size ground state search, see Sec. Infinite-size ground state search: iMPS. For finite temperature evolutions via imaginary time evolution choose 'FiniteImag'. Defaults to 'Finite'.	N
unique_ID	String which distinguishes a simulation from all others with the same 'job_ID'. Defaults to the empty string.	Y
Write_Directory	Directory where files for internal OSMPS use are written. Defaults to current directory.	Y
Output_Directory	Directory where output files are written. Defaults to current directory.	Y
verbose	Integer specifying the level of code output, with 0 being the least amount of output and 2 the most. Defaults to 0.	Y
logfile	True writes seperate logfile, false information goes to standard out. Default to False.	Y
hdf5	Settings for the file type of the observables. If false, use human readable text files. If true, use HDF5 files, which implies that the F90 source was compiled with HDF5. Right now, the implementation is for serial simulations / single thread and was not tested for any scenario with multiple simulations at a time, e.g., submitting two serial simulations to a cluster. MPI is disabled internally in the MPSPyLib. Only use false for iMPS. Default to False.	Y Y
strict	Defines the overwrite policy for main and output files. When True files are not overwritten but an error raised. Default to False.	Y
MPSObservables	An object of the Obs.Observables class specifying ground state measurements, see Sec. Defining and reading observables: obsterms.Observables. Defaults to no measurements.	Y
MPSConvergenceParameters	An object of the tools.MPSConvergenceParameters class specifying the convergence criteria imposed on variational ground state search, see Sec. Variational ground state search. Defaults to the default values of tools.MPSConvergenceParameters (see class description)	Y
n_excited_states	Integer number of excited states to be found using eMPS, see Sec. Variational excited state search: eMPS. Defaults to 0.	Y
eMPSConvergenceParameters	An object of the tools.MPSConvergenceParameters class specifying the convergence criteria imposed on variational excited state search, see Sec. Variational excited state search: eMPS. Defaults to the default values of tools.MPSConvergenceParameters (see class description)	Y
eMPSObservables	An object of the Obs.Observables class specifying excited state measurements, see Sec. Defining and reading observables: obsterms.Observables. Defaults to no measurements.	Y
Quenches	An object of the Dynamics.QuenchList class specifying a dynamical process, see Sec. Specification of dynamics. Defaults to None.	Y
DynamicsObservables	An object of the Obs.Observables class class specifying measurements of the time-evolved state, see Sec. Defining and reading observables: obsterms.Observables. Defaults to no measurements.	Y
timeevo_restore	True : try to continue interrupted time evolution; False : start time evolution at t=0. Default to False.	Y
timeevo_mps_initial	Can specicy an input state from file instead of ground state. Default empty string (Ground state).	Y
statics_initial	Define a initial guess for the ground state search. If not specified, guess is generated automatically.	Y
timeevo_mpdo_initial	Initial guess finite-T evolution with symmetries or initial state for time evolution.	Y
Abelian_generators	A list of the keys of generators of Abelian symmetries to be used. See Sec. Abelian symmetries for more on the use of Abelian symmetries. Defaults to no symmetries.	Y
Abelian_quantum_numbers	A list of the quantum numbers corresponding to the generators in 'Abelian_generators'. See Sec. Abelian symmetries for more on the use of Abelian symmetries. Defaults to no quantum numbers.	Y
Discrete_generators	not enables yet. Raises exception
MPDO+	Logical, used to switch to MPDO algorithms in future. Default to False.	Y
QT	Sampling over realizations of the same simulation, e.g. in future used for quantum trajectories. Default: 1 simulation (not present)	Y

The following keys are set internally:

Key (strings)	Description
Dynamics	True if key Quenches available, else default is False
MPS	if MPSConvergenceParameters given, MPS must be True. Default value is True except for the dynamics with a given initial state defined through the key state.
eMPS	if n_excited_states equal to 0, MPS=True and eMPS=False If > 0, then MPS=True and eMPS=True. If n_excited_states not given, default to False.
int_files	empty list set in this function, changed during the WriteMainFile.
hash	The hash of the static simulations.

tools.CleanFiles(Parameters)

Delete all files generated for the Fortran backend.

Arguments

Parameterslist or single string

tba

tools.append_hash2map(param, Hash)

Append a new information to the mapping of the hashed groundstates / observables.

Arguments

paramDictionary

the dictionary with all the parameters for the simulation

Hashstr

hash for the parameters in param

tools.copy_files_qt(filename, QT)

Makes copies of a file for quantum trajectory appending the corresponding index before the file appendix.

Arguments

filenamestr

file to be copied.

QTint

make QT copies with indices 1 to QT (including QT).

---

class tools.MPSFortLibError(ret_val)

Excpetion raised if the fortran library exits with an error.

Arguments __init__

ret_valint

return code of the fortran library.

__str__()

String representing error message.