pyvibdmc.simulation_utilities ============================= .. py:module:: pyvibdmc.simulation_utilities Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/pyvibdmc/simulation_utilities/Constants/index /autoapi/pyvibdmc/simulation_utilities/file_manager/index /autoapi/pyvibdmc/simulation_utilities/imp_samp/index /autoapi/pyvibdmc/simulation_utilities/imp_samp_helper/index /autoapi/pyvibdmc/simulation_utilities/imp_samp_manager/index /autoapi/pyvibdmc/simulation_utilities/initial_conditioner/index /autoapi/pyvibdmc/simulation_utilities/mpi_imp_samp_manager/index /autoapi/pyvibdmc/simulation_utilities/mpi_potential_manager/index /autoapi/pyvibdmc/simulation_utilities/potential_manager/index /autoapi/pyvibdmc/simulation_utilities/sim_archive/index /autoapi/pyvibdmc/simulation_utilities/sim_logger/index /autoapi/pyvibdmc/simulation_utilities/tensorflow_descriptors/index /autoapi/pyvibdmc/simulation_utilities/xyz_npy/index Classes ------- .. autoapisummary:: pyvibdmc.simulation_utilities.Constants pyvibdmc.simulation_utilities.XYZNPY pyvibdmc.simulation_utilities.Potential pyvibdmc.simulation_utilities.Potential_NoMP pyvibdmc.simulation_utilities.NN_Potential pyvibdmc.simulation_utilities.Potential_Direct pyvibdmc.simulation_utilities.MolFiniteDifference pyvibdmc.simulation_utilities.HarmonicAnalysis pyvibdmc.simulation_utilities.InitialConditioner pyvibdmc.simulation_utilities.DistIt pyvibdmc.simulation_utilities.Potential pyvibdmc.simulation_utilities.Potential_NoMP pyvibdmc.simulation_utilities.NN_Potential pyvibdmc.simulation_utilities.ImpSampManager pyvibdmc.simulation_utilities.ImpSampManager_NoMP pyvibdmc.simulation_utilities.ImpSamp pyvibdmc.simulation_utilities.AnalyzeWfn pyvibdmc.simulation_utilities.ChainRuleHelper Functions --------- .. autoapisummary:: pyvibdmc.simulation_utilities.get_atomic_num pyvibdmc.simulation_utilities.get_atomic_string Package Contents ---------------- .. py:class:: Constants Thanks, Mark Boyer, for this silly little class. Converter that handles energy, distance, and mass conversions for DMC. Can be expanded upon. .. py:attribute:: atomic_units .. py:method:: convert(val, unit, to_AU=True) :classmethod: :param val: The value or values that will be converted :type val: np.ndarray :param unit: The units (not atomic units) that we will be converting to or from :type unit: str :param to_AU: If true, converting from non-a.u. to a.u. If false, converting to a.u. from non-a.u. :type to_AU:boolean :return: converted values .. py:method:: mass(atom, to_AU=True) :classmethod: Given a string that corresponds to an atomic element, output the atomic mass of that element :param atom: The string of an atomic element :type atom:str :param to_AU: If true, converting from non-a.u. to a.u. If false, converting to a.u. from non-a.u. :type to_AU:boolean :return: mass in atomic units unless user changes to_AU to False, then AMU .. py:method:: reduced_mass(atoms, to_AU=True) :classmethod: Given a string like 'O-H' or 'N-N' , output the reduced mass of that diatomic :param atoms: A string that is composed of two atoms :type atom:str :param to_AU: If true, converting from non-a.u. to a.u. If false, converting to a.u. from non-a.u. :type to_AU:boolean :return: mass in atomic units unless user changes to_AU to False, then AMU .. py:function:: get_atomic_num(atms) :param atms: A list (or single string) of atomic element symbols :return: The atomic numbers of each of the atom strings you provide .. py:function:: get_atomic_string(atomic_num) :param atomic_num: The atomic numbers of each of the atom strings you provide :return: A list of atomic element symbols .. py:class:: XYZNPY Handler of xyz <-> npy conversion, like a personal version of openBabel. .. py:method:: extract_xyz(file_name, num_atoms) :staticmethod: Extracts the coordinates from an xyz file and returns it as an np array of dimension nxmx3, where n = number of geometries, m = number of atoms, and 3 = cartesian coordinates :param file_name: Name of the .xyz file, including extension :type file_name: str :param num_atoms: Number of atoms in molecule. :type num_atoms: int :return: nxmx3 numpy array of coordinates .. py:method:: write_xyz(coords, fname, atm_strings, cmt=None) :staticmethod: Writes a numpy array of x,y,z coordinates to a .xyz file :param fname: name of xyz file :param coords: numpy array, either mx3 or nxmx3, where n = number of geometries and m = number of atoms :param atm_strings: list of strings that correspond to the atom type e.g. ["H","H","O"] :return: np.ndarray .. py:class:: Potential(potential_function, potential_directory, python_file, num_cores=1, pass_timestep=False, pot_kwargs=None) A potential handler that is able to call python functions that call .so files, either generated by f2py or loaded in by ctypes. :param potential_function: The name of a python function (user specified) that will take in a n x m x 3 stack of geometries and return a 1D numpy array filled with potential values in hartrees. :type potential_function: str :param potential_dir: The *absolute path* to the directory that contains the .so file and .py file. If it"s a python function, then just the absolute path to your .py file. :type: str :param num_cores: Will create a pool of processes using Python"s multiprocessing module. This should never be larger than the number of processors on the machine this code is run. :type: int .. py:attribute:: potential_function .. py:attribute:: python_file .. py:attribute:: potential_directory .. py:attribute:: num_cores :value: 1 .. py:attribute:: pass_timestep :value: False .. py:attribute:: pot_kwargs :value: None .. py:property:: pool Returns the potential manager's pool so that it can be used internally with Imp Samp or with the user elsewhere .. py:method:: getpot(cds, timeit=False) Uses the potential function we got to call potential :param cds: A stack of geometries (nxmx3, n=num_geoms;m=num_atoms;3=x,y,z) whose energies we need :type cds: np.ndarray :param timeit: The logger telling the potential manager whether or not to time the potential call :type timeit: bool .. py:method:: mp_close() .. py:class:: Potential_NoMP(potential_function, potential_directory, python_file, pass_timestep=False, ch_dir=False, pot_kwargs=None) Version of Potential where no multiprocessing is included. As such, it does not leave a worker in the potential directory of interest. If you need to cd into the directory to call a potential (for example, the potential loads in a file using a relative path or something), then use ch_dir=True. Not the default since it is computationally inefficient to cd during each potential call when not necessary. .. py:attribute:: potential_function .. py:attribute:: python_file .. py:attribute:: pass_timestep :value: False .. py:attribute:: potential_directory .. py:attribute:: pot_kwargs :value: None .. py:attribute:: ch_dir :value: False .. py:method:: getpot(cds, timeit=False) Uses the potential function we got to call potential :param cds: A stack of geometries (nxmx3, n=num_geoms;m=num_atoms;3=x,y,z) whose energies we need :type cds: np.ndarray :param timeit: The logger telling the potential manager whether or not to time the potential call :type timeit: bool .. py:class:: NN_Potential(potential_function, potential_directory, python_file, model, ch_dir=False, pot_kwargs=None, pass_timestep=False) Bases: :py:obj:`Potential_NoMP` Subclass of Potential_NoMP, where a model argument is provided for convenience .. py:attribute:: model .. py:attribute:: ch_dir :value: False .. py:attribute:: pot_kwargs :value: None .. py:method:: getpot(cds, timeit=False) Subclass of Potential_NoMP, but with an explicit argument passed for the NN model for convenience. .. py:class:: Potential_Direct(potential_function, pot_kwargs=None, pass_timestep=False) Version of Potential where the actual Python function is passed rather than being imported from an external file. At the request of Mark. .. py:attribute:: potential_function .. py:attribute:: pot_kwargs :value: None .. py:attribute:: pass_timestep :value: False .. py:method:: getpot(cds, timeit=False) .. py:class:: MolFiniteDifference Helper to calculate derivatives of some value as a function of Cartesian displacements in a molecule. .. py:attribute:: weights_der1 .. py:attribute:: weights_der2 .. py:method:: displace_molecule(eq_geom, atm_cd, dx, num_disps) :staticmethod: Displace atm along cd :param eq_geom: Geometry from which you will be displaced :param atm_cd: a tuple that has a paricular atom of interest to displace in a particular dimension (x,y,or,z) :param dx: The amount each geometry will be replaced :param num_disps: int of how many displacements to do, will take the form of 3 or 5 for harmonic analysis. :return: Displaced coordinates in a 3D array (n,m,3). If displaced in two directions, then still (n,m,3) .. py:method:: differentiate(values, dx, num_points, der) :classmethod: .. py:class:: HarmonicAnalysis(eq_geom, atoms, potential, masses=None, dx=0.001, points_diag=5, points_off_diag=3, dipole=None) .. py:attribute:: eq_geom .. py:attribute:: atoms .. py:attribute:: potential .. py:attribute:: masses :value: None .. py:attribute:: dx :value: 0.001 .. py:attribute:: points_diag :value: 5 .. py:attribute:: points_off_diag :value: 3 .. py:attribute:: num_elems .. py:attribute:: dipole :value: None .. py:method:: generate_hessian() .. py:method:: dipole_derivs() .. py:method:: diagonalize(hessian) .. py:method:: run() .. py:class:: InitialConditioner(coord, atoms, num_walkers, technique, technique_kwargs, masses=None) If given a minimum energy geometry of the system you are trying to run, it will generate a preliminary ensemble. In one instance, you can calculate the harmonic frequencies and normal modes, and then sample the harmonic 3N-6 ground state wave function along those normal modes. Will, in the future, handle other initial conditions. .. py:attribute:: coord .. py:attribute:: atoms .. py:attribute:: masses :value: None .. py:attribute:: num_walkers .. py:attribute:: technique .. py:attribute:: technique_kwargs .. py:method:: gen_disps(sigmas) .. py:method:: displace_along_nms(freqz, nmz, massez, ensemble) .. py:method:: run_harm() .. py:method:: run_permute() Must pass in a list of lists. .. py:method:: run() .. py:class:: DistIt(zs, method, eq_xyz=None, sorted_groups=None, sorted_atoms=None, full_mat=False, force_numpy=False) Calculates the Distance matrix, coulomb matrix, or SPF matrix (delta_r / r) for a given molecule. Returns a cupy or numpy multidimensional array. If cupy is installed, this will default to using it. This means in the run(cds) function, you must pass cds as a cupy array .. py:attribute:: zs .. py:attribute:: method .. py:attribute:: eq_xyz :value: None .. py:attribute:: sorted_groups :value: None .. py:attribute:: sorted_atoms :value: None .. py:attribute:: full_mat :value: False .. py:attribute:: force_numpy :value: False .. py:method:: check_cupy() .. py:method:: dist_matrix(atm_vec) If full matrix required, calculate it here. .. py:method:: atm_atm_dists(cds) Takes in coordinates, will return a vector of the atm-atm dists. .. py:method:: sort_atoms(d_mat) .. py:method:: sort_groups(d_mat) Swap 2 or more groups of atoms according to the sum of the norm of the group's columns. Only one type of group can swapped. .. py:method:: get_prepped_vec(atm_atm_vec) .. py:method:: run(cds) Takes in cartesian coordinates, outputs the descriptor matrix in either vector form (upper triangle) or matrix form. .. py:class:: Potential(potential_function, potential_directory, python_file, num_cores=1, pass_timestep=False, pot_kwargs=None) A potential handler that is able to call python functions that call .so files, either generated by f2py or loaded in by ctypes. :param potential_function: The name of a python function (user specified) that will take in a n x m x 3 stack of geometries and return a 1D numpy array filled with potential values in hartrees. :type potential_function: str :param potential_dir: The *absolute path* to the directory that contains the .so file and .py file. If it"s a python function, then just the absolute path to your .py file. :type: str :param num_cores: Will create a pool of processes using Python"s multiprocessing module. This should never be larger than the number of processors on the machine this code is run. :type: int .. py:attribute:: potential_function .. py:attribute:: python_file .. py:attribute:: potential_directory .. py:attribute:: num_cores :value: 1 .. py:attribute:: pass_timestep :value: False .. py:attribute:: pot_kwargs :value: None .. py:property:: pool Returns the potential manager's pool so that it can be used internally with Imp Samp or with the user elsewhere .. py:method:: getpot(cds, timeit=False) Uses the potential function we got to call potential :param cds: A stack of geometries (nxmx3, n=num_geoms;m=num_atoms;3=x,y,z) whose energies we need :type cds: np.ndarray :param timeit: The logger telling the potential manager whether or not to time the potential call :type timeit: bool .. py:method:: mp_close() .. py:class:: Potential_NoMP(potential_function, potential_directory, python_file, pass_timestep=False, ch_dir=False, pot_kwargs=None) Version of Potential where no multiprocessing is included. As such, it does not leave a worker in the potential directory of interest. If you need to cd into the directory to call a potential (for example, the potential loads in a file using a relative path or something), then use ch_dir=True. Not the default since it is computationally inefficient to cd during each potential call when not necessary. .. py:attribute:: potential_function .. py:attribute:: python_file .. py:attribute:: pass_timestep :value: False .. py:attribute:: potential_directory .. py:attribute:: pot_kwargs :value: None .. py:attribute:: ch_dir :value: False .. py:method:: getpot(cds, timeit=False) Uses the potential function we got to call potential :param cds: A stack of geometries (nxmx3, n=num_geoms;m=num_atoms;3=x,y,z) whose energies we need :type cds: np.ndarray :param timeit: The logger telling the potential manager whether or not to time the potential call :type timeit: bool .. py:class:: NN_Potential(potential_function, potential_directory, python_file, model, ch_dir=False, pot_kwargs=None, pass_timestep=False) Bases: :py:obj:`Potential_NoMP` Subclass of Potential_NoMP, where a model argument is provided for convenience .. py:attribute:: model .. py:attribute:: ch_dir :value: False .. py:attribute:: pot_kwargs :value: None .. py:method:: getpot(cds, timeit=False) Subclass of Potential_NoMP, but with an explicit argument passed for the NN model for convenience. .. py:class:: ImpSampManager(trial_function, trial_directory, python_file, pot_manager, pass_timestep=False, new_pool_num_cores=None, deriv_function=None, trial_kwargs=None, deriv_kwargs=None) Imports and Wraps around the user-provided trial wfn and (optionally) the first and second derivatives. Parallelized using multiprocessing, which is considered the default for pyvibdmc. .. py:attribute:: trial_func .. py:attribute:: trial_dir .. py:attribute:: python_file .. py:attribute:: deriv_func :value: None .. py:attribute:: trial_kwargs :value: None .. py:attribute:: deriv_kwargs :value: None .. py:attribute:: pot_manager .. py:attribute:: pass_timestep :value: False .. py:attribute:: nomp_pool_cores :value: None .. py:method:: call_trial(cds) Get trial wave function using multiprocessing .. py:method:: call_trial_no_mp(cds) For call_derivs (finite diff), get trial wave function. Still used in the mp.pool context, just doesn't call pool itself .. py:method:: call_derivs(cds) For when derivatives are not supplied, call finite difference function. This is still parallelized. .. py:class:: ImpSampManager_NoMP(trial_function, trial_directory, python_file, chdir=False, pass_timestep=False, deriv_function=None, trial_kwargs=None, deriv_kwargs=None) Version of the manager that does not use any multiprocessing. If we ever evaluate the trial wfns with GPUs this could be useful. Could also be useful if multiprocessing is incompatible with your workflow. .. py:attribute:: trial_fuc .. py:attribute:: trial_dir .. py:attribute:: python_file .. py:attribute:: pass_timestep :value: False .. py:attribute:: deriv_func :value: None .. py:attribute:: trial_kwargs :value: None .. py:attribute:: deriv_kwargs :value: None .. py:attribute:: chdir :value: False .. py:method:: call_imp_func(func, cds, func_kwargs=None) Convenience function for trial, deriv, and sderiv so I don't have to have triplicates of code .. py:method:: call_trial(cds) Call trial wave function. .. py:method:: call_derivs(cds) For when derivatives are not supplied, call finite difference function. Returns derivatives divided by psi already .. py:class:: ImpSamp(imp_samp_manager) Internal class that: 1. Calculates local energy 2. Calculates drift terms 3. Calls trial wave function Directly interfaces with the simulation. Also a good place to put finite difference derivatives. .. py:attribute:: imp_manager .. py:method:: trial(cds) Internally returns the direct product wfn .. py:method:: drift(cds) Internally returns (dpsi/psi), since it's more convenient in the workflow. Also returns second derivatives divided by psi .. py:method:: metropolis(sigma_trip, trial_x, trial_y, disp_x, disp_y, D_x, D_y, dt) :staticmethod: .. py:method:: local_kin(inv_masses_trip, sec_deriv) :staticmethod: .. py:method:: finite_diff(cds, trial_func) :staticmethod: Internal finite diff of needed derivatives for imp samp DMC, dpsi/dx and d2spi/dx2 .. py:class:: AnalyzeWfn(coordinates) .. py:attribute:: xx .. py:method:: dot_pdt(v1, v2) :staticmethod: Takes two stacks of vectors and dots the pairs of vectors together .. py:method:: exp_val(operator, dw) :staticmethod: Calculation of an expectation value using Monte Carlo Integration :param operator: array of bond lengths, bond angles, potentials, dipole moments, etc. :type operator: np.ndarray :param dw: Descendant Weights :type dw: np.ndarray :return: Expectation value (single float) .. py:method:: bond_length(atm1, atm2) Computes the norm of the vector between two atoms. :param atm1: desired atom number 1 (python index starts at 0) :type atm1: int :param atm2: desired atom number 2 :type atm2: int :return: norm of x[atm1]-x[atm2] .. py:method:: bond_angle(atm1, atm_vert, atm3) Calculate atm1 - atm_vert - atm3 angle :param atm1: Index of the first external atom (python index starts at 0) :type atm1: int :param atm_vert: Index of the atom at the vertex (python index starts at 0) :type atm_vert: int :param atm3: Index of the second external atom (python index starts at 0) :type atm3: int :return: Angle in radians .. py:method:: bisecting_vector(atm1, atm_vert, atm3) Get normalized bisecting vector of two vectors (two bond lengths). It is assumed that the two flanking atoms have the same central atom. |b|*a + |a|*b :param atm1: Index of the first external atom (python index starts at 0) :type atm1: int :param atm_vert: Index of the atom at the vertex (python index starts at 0) :type atm_vert: int :param atm3: Index of the second external atom (python index starts at 0) :type atm3: int :return: normalized bisecting vector .. py:method:: dihedral(atm_1, atm_2, atm_3, atm_4) Defines the dihedral coordinate using 3 vectors. vec_1 and vec_2 form a plane, and vec_2 and vec_3 form a plane. The dihedral angle is the calculated angle betwen these two planes. The sign is dependent on the direction of the vectors, as the cross product is taken between the two pairs of two vectors https://stackoverflow.com/questions/20305272/dihedral-torsion-angle-from-four-points-in-cartesian-coordinates-in-python https://en.wikipedia.org/w/index.php?title=Dihedral_angle&oldid=689165217#Angle_between_three_vectors .. py:method:: get_component(atm, xyz) Get x, y, or z component of a vector that corresponds to a particular atom in some predetermined cooridnate system. :param atm: atom's index in numpy array :type: int :param xyz: Either 0 (x), 1 (y), or 2 (z) :type xyz: int :return: vector of x, y, or z components of a stack of vectors .. py:method:: cart_to_spherical(vecc) :staticmethod: Takes stack of cartesian vectors (nx3) and translates them to stack of r theta phi coordinates, with the assumption that you are already in the coordinate frame you desire. .. py:method:: projection_1d(attr, desc_weights, bins=25, range=None, normalize=True) :staticmethod: Project the probability amplitude onto a particular coordinate, 1D Histogram. :param attr: the coordinate to be projected onto (bond length, bond angle, etc.) :type attr: np.ndarray :param desc_weights: the descendant weights for \psi**2 :type desc_weights: np.ndarray :param bins: Number of bins in histogram (higher number, more number of walkers needed) :type attr: int :param range: Range over which attr is histogrammed :type range: tuple :param normalize: Normalizes the wave function along coordinate :type attr: bool :return: np.ndarray of shape (bin_num-1 x 2), bin centers, amplitude at bin centers .. py:method:: projection_2d(attr1, attr2, desc_weights, bins=[25, 25], range=None, normalize=True) :staticmethod: Project the probability amplitude onto a 2 coordinates, 2D Histogram. :param attr1: coordinate 1 to be projected onto (bond length, bond angle, etc.) :type attr: np.ndarray :param attr2: coordinate 2 to be projected onto (bond length, bond angle, etc.) :type attr: np.ndarray :param desc_weights: the descendant weights for \psi**2 :type desc_weights: np.ndarray :param bins: Number of bins for histogram in both directions (higher number, more number of walkers needed) :type attr: tuple :param range: Range over which attr is histogrammed :type range: list of two tuples :param normalize: Normalizes the wave function along both coordinates (integrated area under 2D surface is 1) :type attr: bool :return: np.ndarray of shape (bin_num-1 x 2), bin centers x, bin centers y, and then the 2D array with amplitude. .. py:class:: ChainRuleHelper(coords, module) .. py:attribute:: cds .. py:attribute:: xp .. py:attribute:: analyzer .. py:method:: dpsidx(dpsi_dr, dr_dx) Generic function that takes in a series of dpsi/dr matrices and dr/dx matrices and generates the dpsi/dx matrix. Assumes direct product wave function fed in appropriately. .. py:method:: d2psidx2(d2psi_dr2, d2r_dx2, dpsi_dr, dr_dx) Generic function that takes in a series of d2psi_dr2 and d2r/dx matrices and generates the second derivative of psi wrt x, doing out the chain rule explicitly. .. py:method:: dr_dx(atm_pair) calculates the dr/dx first derivatives for bond lengths :param self.cds: num_walkers x num_atms x 3 array :param atm_bonds: list of bond lengths that are relevant to the trial wave function. like [0,1] :return: num_walkers x num_atoms x 3 array of dr/dx .. py:method:: d2r_dx2(atm_pair, dr_dx=None) Calculates d2r/dx2 second derivatives for bond lengths .. py:method:: dcth_dx(atm_pair, cos_theta=None, dr_da=None, dr_dc=None) calculates the dcos(theta)/dx first derivatives for bond lengths :param self.cds: num_walkers x num_atms x 3 array :param atm_pair: list of bond lengths that are relevant to the trial wave function. like [0,2,1]. ALWAYS put vertex of angle in middle index atm_bonds[x][1]. :param dr_das: The derivative of the bond length corresponding to atm_bonds[i][0] and atm_bonds[i][1]. i is the index of the atm_bonds list of lists :param dr_dcs: The derivative of the bond length corresponding to atm_bonds[i][1] and atm_bonds[i][2]. i is the index of the atm_bonds list of lists :return: len(atm_bonds) x num_walkers x num_atoms x 3 array of dr/dx .. py:method:: d2cth_dx2(atm_pair, cos_theta=None, dr_da=None, dr_dc=None, d2r_da2=None, d2r_dc2=None) :param self.cds: num_walkers x num_atms x 3 array :param atm_bonds: list of lists of bond lengths that are relevant to the trial wave function. like [[0,2,1]]. ALWAYS put vertex of angle in middle index atm_bonds[x][1]. :param dr_das: The derivative of the bond length corresponding to atm_bonds[i][0] and atm_bonds[i][1]. i is the index of the atm_bonds list of lists :param dr_dcs: The derivative of the bond length corresponding to atm_bonds[i][1] and atm_bonds[i][2]. i is the index of the atm_bonds list of lists :param d2r_da2s: The second derivative of the bond length corresponding to atm_bonds[i][0] and atm_bonds[i][1]. i is the index of the atm_bonds list of lists :param d2r_dc2s: The second derivative of the bond length corresponding to atm_bonds[i][1] and atm_bonds[i][2]. i is the index of the atm_bonds list of lists .. py:method:: dth_dx(atm_pair, cos_theta=None, dcth_dx=None, dr_da=None, dr_dc=None) :param self.cds: num_walkers x num_atoms x 3 array :param atm_pair: list that corresponds to indices of the ABC angle, where B is the vertex :param dcth_dxs: Derivative of cosine theta wrt x. This is needed for this derivative and the second derivative. .. py:method:: d2th_dx2(atm_pair, cos_theta=None, dcth_dx=None, dr_da=None, dr_dc=None, d2r_da2=None, d2r_dc2=None) :param self.cds: num_walkers x num_atoms x 3 array :param atm_pair: list that corresponds to indices of the ABC angle, where B is the vertex :param dcth_dxs: Derivative of cosine theta wrt x. This is needed for this derivative and the second derivative.