schrodinger.application.matsci.mecp_mod module¶
Classes and functions for finding MECPs.
Copyright Schrodinger, LLC. All rights reserved.
-
schrodinger.application.matsci.mecp_mod.
rosen
(x_vec)¶ The Rosenbrock function. The target solution should be all ones and the function value here should be zero.
Parameters: x_vec (numpy.array) – the solution vector (N X 1) Return type: float, numpy.array Returns: the function value and Jacobian (N X 1)
-
schrodinger.application.matsci.mecp_mod.
quadratic_1
(x_vec)¶ The x**2 + y**2 + 2*x function. The target solution is (x = -1, y = 0) with f = -1. The minimum crossing point with quadratic_2 is (x = -1/2, y = -1/2).
Parameters: x_vec (numpy.array) – the solution vector (N X 1) Return type: float, numpy.array Returns: the function value and Jacobian (N X 1)
-
schrodinger.application.matsci.mecp_mod.
quadratic_2
(x_vec)¶ The x**2 + y**2 + 2*y function. The target solution is (x = 0, y = -1) with f = -1. The minimum crossing point with quadratic_1 is (x = -1/2, y = -1/2).
Parameters: x_vec (numpy.array) – the solution vector (N X 1) Return type: float, numpy.array Returns: the function value and Jacobian (N X 1)
-
schrodinger.application.matsci.mecp_mod.
quadratic_3
(x_vec)¶ The x**2 + y**2 + 6*x function. The target solution is (x = -3, y = 0) with f = -9. The minimum crossing point with quadratic_2 is (x = -3/10, y = -9/10).
Parameters: x_vec (numpy.array) – the solution vector (N X 1) Return type: float, numpy.array Returns: the function value and Jacobian (N X 1)
-
schrodinger.application.matsci.mecp_mod.
get_guess
(nvar=33, amp=5, seed=123)¶ Return a guess solution.
Parameters: - nvar (int) – the number of variables
- amp (int) – the amplitude of the set of random numbers used in generating the guess solution
- seed (int) – seed for random
Return type: numpy.array
Returns: the guess geometry (N X 1)
-
schrodinger.application.matsci.mecp_mod.
set_e_and_g
(astructure, jobs)¶ Set the energies and gradients for a debug run.
Parameters: - astructure (
schrodinger.structure.Structure
) – the structure containing the solution as coordinates - jobs (list) – contains instances of JaguarJob
- astructure (
-
class
schrodinger.application.matsci.mecp_mod.
ParserWrapper
(scriptname, description)¶ Bases:
object
Manages the argparse module to parse user command line arguments.
-
loadIt
()¶ Load ParserWrapper with options.
-
parseArgs
(args)¶ Parse the command line arguments.
Parameters: args (tuple) – command line arguments
-
-
exception
schrodinger.application.matsci.mecp_mod.
InputError
¶ Bases:
Exception
-
class
schrodinger.application.matsci.mecp_mod.
CheckInput
¶ Bases:
object
Manages checking input.
-
static
checkChargeAndMultiplicity
(astructure, charge, multiplicity)¶ Check the charge and multiplicity.
Parameters: - astructure (
schrodinger.structure.Structure
) – the structure to check - charge (int) – net molecular charge
- multiplicity (int) – net molecular multiplicity
Raise: InputError if there is an issue
- astructure (
-
static
checkChargesMultiplicitiesStates
(charge_1, charge_2, multip_1, multip_2, state_1, state_2)¶ Check the charges, multiplicities, and states.
Parameters: - charge_1 (int) – the charge of the first state
- charge_2 (int) – the charge of the second state
- multip_1 (int) – the multiplicity of the first state
- multip_2 (int) – the multiplicity of the second state
- state_1 (int) – the first state, 0 for ground state, N for the N-th excited state
- state_2 (int) – the second state, 0 for ground state, N for the N-th excited state
Raise: InputError if there is an issue
-
static
checkParallelization
(tpp, nresources)¶ Check the parallelization options.
Parameters: - tpp (int) – the number of threads to use for this Jaguar job, i.e. -TPP (threads-per-process)
- nresources (int) – the number of resources for Jaguar calculations, i.e. the number of threads * the number of processors
Raise: InputError if there is an issue
-
static
-
schrodinger.application.matsci.mecp_mod.
get_final_state
(state, scf_gs, multiplicity)¶ Return the final state.
Parameters: - state (int) – the electronic state, 0 is the ground state and <N> is the N-th excited state
- scf_gs (bool) – specify whether ground states should be determined using an SCF
- multiplicity (int) – molecular multiplicity
Return type: int or None
Returns: the final state or None if there isn’t one
-
class
schrodinger.application.matsci.mecp_mod.
JaguarJob
(idx=None, base_name=None, charge=None, multiplicity=None, state=None, scf_gs=None, kwargs=None, mae_input_file=None, jag_input_file=None, jag_output_file=None, jag_restart_input_file=None, in_template=None, job=None)¶ Bases:
object
Manages a Jaguar job.
-
KEYS
= ['idx', 'base_name', 'charge', 'multiplicity', 'state', 'scf_gs', 'kwargs', 'mae_input_file', 'jag_input_file', 'jag_output_file', 'jag_restart_input_file', 'in_template', 'job']¶
-
getFinalTotalEnergy
()¶ Return the final total energy accounting for any excitation energies.
Return type: float Returns: the total energy in hartree
-
getFinalForcesHartreePerAngstrom
()¶ Return the final forces in units of hartree/angstrom.
Return type: numpy.array Returns: the forces in hartree/angstrom in natoms X 3
-
getFinalStructure
()¶ Return the final structure.
Parameters: astructure ( schrodinger.structure.Structure
) – the final structure
-
-
exception
schrodinger.application.matsci.mecp_mod.
JaguarError
¶ Bases:
Exception
-
class
schrodinger.application.matsci.mecp_mod.
JaguarJobs
(data=[(0, 3, 0), (0, 1, 1)], scf_gs=False, kwargs={'basis': 'MIDIX', 'dftname': 'B3LYP', 'iacc': 1, 'isymm': 0, 'itda': 1, 'itddft': 1, 'iuhf': 2, 'maxit': 100, 'nofail': 0, 'nops': 1}, base_name='mecp', host='localhost', nproc=2, tpp=1, logger=None)¶ Bases:
object
Manages Jaguar jobs.
-
EXTRA_NROOT
= 4¶
-
clearJobs
()¶ Clear the list of jobs attribute.
-
setStructure
(astructure)¶ Set the structure to use for the jobs.
Parameters: astructure ( schrodinger.structure.Structure
) – the structure to use for the jobs
-
setInTemplates
(in_templates=None)¶ Set the input templates to use for the jobs.
Parameters: in_templates (list or None) – a list of Jaguar input files to use as templates for creating the jobs, if used then the length of this list should be equivalent to that of the data attribute, the first ZMAT section is overwritten with the input astructure argument, use None if there aren’t any templates Raise: JaguarError if in_templates data is the wrong size
-
setUpLaunchDir
(launch_dir=None)¶ Set up the launch directory for the jobs.
Parameters: launch_dir (str or None) – the directory from which to launch the jobs or None if there isn’t one (in which case the CWD will be used)
-
getBaseName
(idx)¶ Return a base name for the given job.
Parameters: idx (int) – the job index Return type: str Returns: base name for the job
-
getKwargs
(charge, multiplicity, state)¶ Return the kwargs for the given job.
Parameters: - charge (int) – net molecular charge
- multiplicity (int) – molecular multiplicity
- state (int) – the electronic state, 0 is the ground state and <N> is the N-th excited state
Return type: dict
Returns: Jaguar kwargs for the job
-
getFileNames
(base_name)¶ Return a list of files names for the given job.
Parameters: base_name (str) – base name for the job Return type: list Returns: file names for the job
-
getInTemplate
(idx)¶ Return an input template file.
Parameters: idx (int) – the job index Return type: str Returns: the input template file
-
getJob
(base_name, jag_input_file)¶ Return a queue.JobControlJob for the given job.
Parameters: - base_name (str) – base name for the job
- jag_input_file (str) – Jaguar input file for the job
Return type: Returns: the job object
-
setUpInputFiles
(job)¶ Set up the input files for the job.
Parameters: job (JaguarJob) – a JaguarJob object containing various job parameters
-
runJobs
()¶ Run the jobs.
-
processOutput
()¶ Process the output from the jobs.
Raise: JaguarError if there were problems with the job
-
runIt
(astructure, in_templates=None, launch_dir=None)¶ Main function to run the jobs.
Parameters: - astructure (
schrodinger.structure.Structure
) – the structure to use for the jobs - in_templates (list or None) – a list of Jaguar input files to use as templates for creating the jobs, if used then the length of this list should be equivalent to that of the data attribute, the first ZMAT section is overwritten with the input astructure argument, use None if there aren’t any templates
- launch_dir (str or None) – the directory from which to launch the jobs or None if there isn’t one (in which case the CWD will be used)
Return type: list
Returns: contains JaguarJob objects for all jobs
- astructure (
-
-
exception
schrodinger.application.matsci.mecp_mod.
TerminateException
¶ Bases:
Exception
-
exception
schrodinger.application.matsci.mecp_mod.
IterationError
¶ Bases:
Exception
-
class
schrodinger.application.matsci.mecp_mod.
MECPStep
(iteration, call_number, x_initial, method, perp_factor, para_factor, verbose, logger, bfgs_obj)¶ Bases:
object
Manage an MECP step, which can be an iteration or a line search iteration.
-
ALPHA_THRESH
= 1e-10¶
-
logInitialGeometry
()¶ Log the initial geometry.
-
logHessianEigVals
()¶ Log the Hessian eigenvalues.
-
logStepInfo
()¶ Log the step info.
-
handleFinalGeometry
(x_final)¶ Handle the final geometry.
Parameters: x_final (numpy.array) – the final geometry vector (N X 1)
-
setInTemplates
()¶ Set the Jaguar input templates.
-
getUnitNormalToDeltaForces
(prev_mecp_step=None)¶ Get the unit vector that is normal to the delta forces vector.
Parameters: prev_mecp_step (MECPStep or None) – MECPStep from the previous iteration or line search iteration or None if there isn’t one Return type: numpy.array or None Returns: the unit vector perpendicular to the delta forces vector or None if there isn’t one
-
setEnergiesAndForces
(prev_mecp_step=None)¶ Set the energies and forces for the two states as well as well as the energy and forces to use for the MECP optimization.
Parameters: prev_mecp_step (MECPStep or None) – MECPStep from the previous iteration or line search iteration or None if there isn’t one
-
setEnergiesAndForcesData
(prev_mecp_step=None)¶ Set energies and forces data.
Parameters: prev_mecp_step (MECPStep or None) – MECPStep from the previous iteration or line search iteration or None if there isn’t one
-
setJobData
(jobs, prev_mecp_step=None)¶ Set job data.
Parameters: - jobs (list) – contains the JaguarJob instances for the two jobs
- prev_mecp_step (MECPStep or None) – MECPStep from the previous iteration or line search iteration or None if there isn’t one
-
logEnergyAndForces
(header, energy, forces, max_force, rms_force, len_force, energy_header='Energy / Hartree', forces_header='Forces / Hartree/Ang.')¶ Log energy and forces.
Parameters: - header (str) – a header
- energy (float or None) – the energy or None if there isn’t one
- forces (numpy.array) – the forces (natoms X 3)
- max_force (float) – the magnitude of the largest forces element
- rms_force (float) – the RMS of forces
- len_force (float) – the length of forces
- energy_header (str) – an energy header
- forces_header (str) – a forces header
-
getFormattedSummaryLine
(entries)¶ Return a formatted summary line from the given data entries.
Parameters: entries (list) – the data to format Return type: str Returns: a formatted summary line
-
logSummaryHeader
()¶ Log the summary header.
-
logSummary
()¶ Log a summary.
-
logJobData
()¶ Log job data.
-
terminate
(convergence_dict)¶ Terminate the MECP optimization.
Parameters: convergence_dict (dict) – contains various convergence thresholds Raise: TerminateException if it is time to terminate
-
-
exception
schrodinger.application.matsci.mecp_mod.
MinimizerError
¶ Bases:
Exception
-
class
schrodinger.application.matsci.mecp_mod.
BFGS
(c1=0.0001, c2=0.9, amax=50.0, amin=1e-08, xtol=1e-14, max_force=0.0001, max_iterations=50, eps=0.0001, init_hess='identity', verbose=False, logger=None)¶ Bases:
object
Manage a BFGS optimization.
-
LARGE_RHO_K
= 1000.0¶
-
IMAG_TOL
= 1e-06¶
-
ANGLE_TOL
= 0.01¶
-
NEG_HESS_TOL
= -0.01¶
-
line_search_wolfe1
(f, fprime, xk, pk, gfk=None, old_fval=None, old_old_fval=None, args=(), c1=0.0001, c2=0.9, amax=50, amin=1e-08, xtol=1e-14)¶ As
scalar_search_wolfe1
but do a line search to directionpk
- f : callable
- Function
f(x)
- fprime : callable
- Gradient of
f
- xk : array_like
- Current point
- pk : array_like
- Search direction
- gfk : array_like, optional
- Gradient of
f
at pointxk
- old_fval : float, optional
- Value of
f
at pointxk
- old_old_fval : float, optional
- Value of
f
at point precedingxk
The rest of the parameters are the same as for
scalar_search_wolfe1
.- stp, f_count, g_count, fval, old_fval
- As in
line_search_wolfe1
- gval : array
- Gradient of
f
at the final point
-
scalar_search_wolfe1
(phi, derphi, phi0=None, old_phi0=None, derphi0=None, c1=0.0001, c2=0.9, amax=50, amin=1e-08, xtol=1e-14)¶ Scalar function search for alpha that satisfies strong Wolfe conditions
alpha > 0 is assumed to be a descent direction.
- phi : callable phi(alpha)
- Function at point
alpha
- derphi : callable dphi(alpha)
- Derivative
d phi(alpha)/ds
. Returns a scalar. - phi0 : float, optional
- Value of
f
at 0 - old_phi0 : float, optional
- Value of
f
at the previous point - derphi0 : float, optional
- Value
derphi
at 0 - amax : float, optional
- Maximum step size
- c1, c2 : float, optional
- Wolfe parameters
- alpha : float
- Step size, or None if no suitable step was found
- phi : float
- Value of
phi
at the new pointalpha
- phi0 : float
- Value of
phi
atalpha=0
Uses routine DCSRCH from MINPACK.
-
resetFiniteDiffCall
()¶ Reset the finite difference call.
-
getInitialInvHessian
(fun, jac, fun_0, jac_0, x_0)¶ Return an initial guess for the inverse Hessian.
Parameters: - fun (function) – function to minimize
- jac (function) – the Jacobian of the function being minimized
- fun_0 (float) – function value at initial solution
- jac_0 (float) – the Jacobian value at initial solution
- x_0 (numpy.array) – initial solution
Return type: numpy.array
Returns: the initial guess inverse Hessian (N/3 X 3)
-
minimize
(fun, x_0, jac=None, **kwargs)¶ Minimization of a function using the BFGS algorithm.
Parameters: - fun (function) – function to minimize
- x_0 (numpy.array) – initial solution
- jac (function) – the Jacobian of the function being minimized
Return type: scipy.optimize.optimize.OptimizeResult
Returns: optimization parameters
-
-
class
schrodinger.application.matsci.mecp_mod.
EnergyAndGradients
(astructure, data=[(0, 3, 0), (0, 1, 1)], scf_gs=False, kwargs={'basis': 'MIDIX', 'dftname': 'B3LYP', 'iacc': 1, 'isymm': 0, 'itda': 1, 'itddft': 1, 'iuhf': 2, 'maxit': 100, 'nofail': 0, 'nops': 1}, base_name='mecp', all_results=False, convergence_dict={'delta_energy': -1e-06, 'max_displacement': 1e-05, 'max_force': 0.0001, 'rms_displacement': 1e-05, 'rms_force': 0.0001}, max_iterations=50, method='projection', perp_factor=100.0, para_factor=1.0, all_geometries=False, host='localhost', nproc=2, tpp=1, verbose=False, logger=None, bfgs_obj=None)¶ Bases:
object
Manage energy and gradient calls.
-
setUpMaeWriter
()¶ Set up the Maestro output writer.
-
tearDownMaeWriter
(exception)¶ Tear down the Maestro output writer and then raise an exception.
Parameters: exception (Exception) – the exception to raise after tear down
-
resetCallNumber
()¶ Reset the call number.
-
setUpJaguarJobs
()¶ Set up for the Jaguar jobs.
-
logHeader
()¶ Log a header.
-
newIteration
()¶ Return True if this is a new iteration.
Return type: bool Returns: True if this is a new iteration, False otherwise
-
setUpIterationLaunchDir
()¶ Set up the launch directory for this MECP iteration.
Return type: str Returns: the launch directory for this MECP iteration
-
getLaunchSubDir
()¶ Return the name of the launch subdirectory for the current job.
Return type: str Returns: the launch subdirectory for the current job
-
runJobs
(launch_dir)¶ Run the jobs.
Parameters: launch_dir (str) – the launch directory for the jobs Return type: list Returns: contains the JaguarJob instances for the two jobs
-
logSummary
()¶ Log a summary.
-
handleStructure
(x_to_use, step=None)¶ Handle setting and writing the structure.
Parameters: - x_to_use (numpy.array) – the geometry vector to use (N X 1)
- step (MECPStep or None) – the step from which to obtain the energy to use or None if there is no energy
-
finishPrevStep
(next_x)¶ Finish the previous step.
Parameters: next_x (numpy.array) – the next geometry vector (N X 1)
-
handleFiniteDifferences
(next_x, finite_diff_call)¶ Handle finite difference calls.
Parameters: - next_x (numpy.array) – the next geometry vector (N X 1)
- finite_diff_call (int) – the index of a finite difference call
Return type: float, numpy.array
Returns: the energy and gradients (N X 1)
-
getEnergyAndGradients
(next_x)¶ Return the energy and gradients that drive the MECP geometry optimization.
Parameters: next_x (numpy.array) – the next geometry vector (N X 1) Return type: float, numpy.array Returns: the energy and gradients (N X 1)
-
-
class
schrodinger.application.matsci.mecp_mod.
MECP
(astructure, charge_1=0, charge_2=0, multip_1=3, multip_2=1, state_1=0, state_2=1, scf_gs=False, jaguar_kwargs={'basis': 'MIDIX', 'dftname': 'B3LYP', 'iacc': 1, 'isymm': 0, 'itda': 1, 'itddft': 1, 'iuhf': 2, 'maxit': 100, 'nofail': 0, 'nops': 1}, iterations=50, eps=0.0001, init_hess='identity', method='projection', perp_factor=100.0, para_factor=1.0, convergence_dict={'delta_energy': -1e-06, 'max_displacement': 1e-05, 'max_force': 0.0001, 'rms_displacement': 1e-05, 'rms_force': 0.0001}, guess_geom='input', all_geometries=False, all_results=False, properties=False, base_name='mecp', tpp=1, nresources=2, verbose=False, logger=None)¶ Bases:
object
Manages finding MECPs.
-
setSCFGS
()¶ Set the SCF ground state.
-
setJaguarKwargs
()¶ Set the Jaguar kwargs.
-
checkInput
()¶ Check input.
-
setParallelization
()¶ Set the parallelization options.
-
setUpMaeWriter
()¶ Set up the Maestro output writer.
-
tearDownMaeWriter
(exception=None)¶ Tear down the Maestro output writer and then raise an exception if there is one.
Parameters: exception (Exception or None) – the exception to raise after tear down or None if there isn’t one
-
logParams
()¶ Log the parameters.
-
doStateOptimizations
()¶ Do the geometry optimizations for the individual states and record their data.
-
getGuessGeometry
()¶ Return the guess geometry.
Return type: numpy.array Returns: the guess geometry (N X 1)
-
postProcessOptimization
(energy_and_gradients)¶ Post process the optimization.
Parameters: energy_and_gradients (EnergyAndGradients) – the instance passed to the optimizer
-
getBFGSObject
(x_0)¶ Return a BFGS object.
Parameters: x_0 (numpy.array) – the guess geometry (N X 1) Return type: BFGS Returns: the object to manage the BFGS optimization
-
getEnergyAndGradientsObject
(bfgs_obj)¶ Return a EnergyAndGradients object.
Parameters: bfgs_obj (BFGS) – the object to manage the BFGS optimization Return type: EnergyAndGradients Returns: the object to manage the energy and gradient calls for the BFGS optimization
-
getOptKwargs
(bfgs_obj)¶ Return the kwargs for the optimization.
Parameters: bfgs_obj (BFGS) – the object to manage the BFGS optimization Return type: dict Returns: the parameters for the optimization
-
optimize
()¶ Optimize the geometry to the MECP.
-
doIncorporation
()¶ Incorporate output Maestro files.
-
runIt
()¶ Main function to find the MECP.
-
-
schrodinger.application.matsci.mecp_mod.
vector_to_matrix
(vector)¶ Convert vector to matrix.
Parameters: vector (numpy.array) – N X 1 array Return type: numpy.array Returns: N/3 X 3 array
-
schrodinger.application.matsci.mecp_mod.
matrix_to_vector
(matrix)¶ Convert matrix to vector.
Parameters: matrix (numpy.array) – N/3 X 3 array Return type: numpy.array Returns: N X 1 array
-
schrodinger.application.matsci.mecp_mod.
get_max_and_rms_and_len
(matrix)¶ Return the max, RMS, and length of the given matrix.
Parameters: matrix (numpy.array) – the matrix Return type: float, float, float Returns: the max, RMS, and length of the given matrix
-
schrodinger.application.matsci.mecp_mod.
log_vector
(vector, header=None, log_sums=False, logger=None)¶ Log or print the given vector in a natoms X 3 format.
Parameters: - vector (numpy.array) – the vector to log (N X 1)
- header (str or None) – a header or None if there isn’t one
- log_sums (bool) – whether to log the sums of x, y, and z over atoms
- logger (logging.Logger or None) – output logger or None if there isn’t one
-
schrodinger.application.matsci.mecp_mod.
log_geometry
(geometry, header='Geometry / Ang.', logger=None)¶ Log or print the geometry in a natoms X 3 format.
Parameters: - geometry (numpy.array) – the geometry to log (N X 1)
- header (str) – a header
- logger (logging.Logger or None) – output logger or None if there isn’t one
-
schrodinger.application.matsci.mecp_mod.
log_displacements
(displacements, max_displacement, rms_displacement, len_displacement, header='Displacements / Ang.', logger=None)¶ Log or print the displacements in a natoms X 3 format.
Parameters: - displacements (numpy.array) – the displacements to log (N X 1)
- max_displacement (float) – the magnitude of the largest displacements element
- rms_displacement (float) – the RMS of displacements
- len_displacement (float) – the length of displacements
- header (str) – a header
- logger (logging.Logger or None) – output logger or None if there isn’t one
-
schrodinger.application.matsci.mecp_mod.
log_energy_and_forces
(energy, forces, max_force, rms_force, len_force, energy_header='Energy / Hartree', forces_header='Forces / Hartree/Ang.', logger=None)¶ Log or print the energy and forces in a natoms X 3 format.
Parameters: - energy (float or None) – the energy or None if there isn’t one
- forces (numpy.array) – the forces to log (N X 1)
- max_force (float) – the magnitude of the largest forces element
- rms_force (float) – the RMS of forces
- len_force (float) – the length of forces
- energy_header (str) – an energy header
- forces_header (str) – a forces header
- logger (logging.Logger or None) – output logger or None if there isn’t one
-
schrodinger.application.matsci.mecp_mod.
reciprocal_bohr_to_angstrom
(array)¶ Return the given array converted from units of reciprocal Bohr to reciprocal Angstrom.
Parameters: array (numpy.array) – the array to convert Return type: numpy.array Returns: the converted array
-
schrodinger.application.matsci.mecp_mod.
ev_to_hartree
(energy)¶ Return the given energy converted from eV to Hartree.
Return type: float Returns: energy in Hartree
-
schrodinger.application.matsci.mecp_mod.
hartree_to_kcal_per_mol
(in_hartree)¶ Return the given energy converted from Hartree to kcal/mol.
Parameters: in_hartree (float) – energy in Hartree Return type: float Returns: energy in kcal/mol
-
schrodinger.application.matsci.mecp_mod.
set_properties_and_write_structure
(astructure, properties, writer)¶ Set the given properties on the structure and write it using the given writer.
Parameters: - astructure (
schrodinger.structure.Structure
) – the structure to write - properties (dict) – key/value pairs of properties to write
- writer (structure.MaestroWriter) – the writer
- astructure (
-
schrodinger.application.matsci.mecp_mod.
get_angle_in_degrees
(vec_1, vec_2)¶ Return the angle in units of degrees between the given two vectors.
Parameters: - vec_1 (numpy.array) – the first vector
- vec_2 (numpy.array) – the second vector
Return type: float
Returns: the angle in degrees