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:
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

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

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:

queue.JobControlJob

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

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 direction pk

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 point xk
old_fval : float, optional
Value of f at point xk
old_old_fval : float, optional
Value of f at point preceding xk

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 point alpha
phi0 : float
Value of phi at alpha=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:
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