Geometry Optimization — optimize() and gradient()

For further discussion of geometry optimization, see Sec. Geometry Optimization.

optimize() is the only command most users will ever need to access directly to perform geometry optimizations. Behind the scenes, optimize() is a wrapper that repeatedly calls gradient() that computes the gradient then adds a call to the geometry optimization module.

psi4.optimize(name[, molecule, return_wfn, func, mode, dertype, hessian_with])[source]

Function to perform a geometry optimization.

Aliases:

opt()

Returns:

float – Total electronic energy of optimized structure in Hartrees.

Returns:

(float, Wavefunction) – energy and wavefunction when return_wfn specified.

Raises:

psi4.driver.OptimizationConvergenceError if GEOM_MAXITER exceeded without reaching geometry convergence.

PSI variables:

Parameters:
  • name (str) –

    'scf' || 'mp2' || 'ci5' || etc.

    First argument, usually unlabeled. Indicates the computational method to be applied to the database. May be any valid argument to psi4.driver.energy().

  • molecule (molecule) –

    h2o || etc.

    The target molecule, if not the last molecule defined.

  • return_wfn (boolean) –

    'on' || \(\Rightarrow\) 'off' \(\Leftarrow\)

    Indicate to additionally return the Wavefunction calculation result as the second element (after float energy) of a tuple.

  • return_history (boolean) –

    'on' || \(\Rightarrow\) 'off' \(\Leftarrow\)

    Indicate to additionally return dictionary of lists of geometries, energies, and gradients at each step in the optimization.

  • engine (str) –

    \(\Rightarrow\) 'optking' \(\Leftarrow\) || 'geometric'

    Indicates the optimization engine to use, which can be either Psi4’s native Optking optimizer or the GeomeTRIC program.

  • optimizer_keywords (dict) –

    Extra options passed to the GeomeTRIC or optking optimizers

    Indicates additional options to be passed to the GeomeTRIC optimizer if chosen as the optimization engine. Alternatively, can be used to set optking options that are not currently recognized by Psi4.

  • func (function) –

    \(\Rightarrow\) gradient \(\Leftarrow\) || energy || cbs

    Indicates the type of calculation to be performed on the molecule. The default dertype accesses 'gradient' or 'energy', while 'cbs' performs a multistage finite difference calculation. If a nested series of python functions is intended (see Function Intercalls), use keyword opt_func instead of func.

  • dertype (dertype) –

    'gradient' || 'energy'

    Indicates whether analytic (if available) or finite difference optimization is to be performed.

  • hessian_with (str) –

    'scf' || 'mp2' || etc.

    Indicates the computational method with which to perform a hessian analysis to guide the geometry optimization.

Warning

Optimizations where the molecule is specified in Z-matrix format with dummy atoms will result in the geometry being converted to a Cartesian representation.

Note

Analytic gradients area available for all methods in the table below. Optimizations with other methods in the energy table proceed by finite differences.

name

calls method

efp

efp-only optimizations

scf

Hartree–Fock (HF) or density functional theory (DFT) [manual] [details]

hf

HF self consistent field (SCF) [manual] [details]

dct

density cumulant (functional) theory [manual]

mp2

2nd-order Møller–Plesset perturbation theory (MP2) [manual] [details]

mp3

3rd-order Møller–Plesset perturbation theory (MP3) [manual] [details]

mp2.5

average of MP2 and MP3 [manual] [details]

omp2

orbital-optimized second-order MP perturbation theory [manual] [details]

omp3

orbital-optimized third-order MP perturbation theory [manual] [details]

omp2.5

orbital-optimized MP2.5 [manual] [details]

oremp2

orbital-optimized REMP2 [manual] [details]

lccd

Linear CCD [manual] [details]

olccd

orbital optimized LCCD [manual] [details]

cc2

approximate coupled cluster singles and doubles (CC2) [manual] [details]

ccd

coupled cluster doubles (CCD) [manual] [details]

ccsd

coupled cluster singles and doubles (CCSD) [manual] [details]

ccsd(t)

CCSD with perturbative triples (CCSD(T)) [manual] [details]

eom-ccsd

equation of motion (EOM) CCSD [manual]

name

calls method DFT [manual]

b1lyp

B1LYP Hyb-GGA Exchange-Correlation Functional

b1lyp-d3bj2b

b1lyp-d3bjatm

b1lyp-d3zero2b

b1lyp-d3zeroatm

b1pw91

B1PW91 Hyb-GGA Exchange-Correlation Functional

b1wc

B1WC Hyb-GGA Exchange-Correlation Functional

b3lyp

B3LYP Hyb-GGA Exchange-Correlation Functional

b3lyp-d3bj2b

b3lyp-d3bjatm

b3lyp-d3mbj2b

b3lyp-d3mbjatm

b3lyp-d3mzero2b

b3lyp-d3mzeroatm

b3lyp-d3zero2b

b3lyp-d3zeroatm

b3lyp-nl

B3LYP-nl Hyb-GGA Exchange-Correlation Functional

b3lyp5

B3LYP5 Hyb-GGA Exchange-Correlation Functional

b3lyps

B3LYPs Hyb-GGA Exchange-Correlation Functional

b3p86

B3P86 Hyb-GGA Exchange-Correlation Functional

b3p86-d3bj2b

b3p86-d3bjatm

b3p86-d3zero2b

b3p86-d3zeroatm

b3pw91

B3PW91 Hyb-GGA Exchange-Correlation Functional

b3pw91-d3bj2b

b3pw91-d3bjatm

b3pw91-d3zero2b

b3pw91-d3zeroatm

b3pw91-nl

B3PW91-nl Hyb-GGA Exchange-Correlation Functional

b5050lyp

B5050LYP Hyb-GGA Exchange-Correlation Functional

b86b95

B86B95 Hyb-GGA Exchange-Correlation Functional

b86bpbe

B86BPBE GGA Exchange-Correlation Functional

b88b95

B88B95 Hyb-GGA Exchange-Correlation Functional

b88b95-d3bj2b

b88b95-d3bjatm

b88b95-d3zero2b

b88b95-d3zeroatm

b97-0

B97-0 Hyb-GGA Exchange-Correlation Functional

b97-1

B97-1 Hyb-GGA Exchange-Correlation Functional

b97-1-d3bj2b

b97-1-d3bjatm

b97-1-d3zero2b

b97-1-d3zeroatm

b97-1p

B97-1p Hyb-GGA Exchange-Correlation Functional

b97-2

B97-2 Hyb-GGA Exchange-Correlation Functional

b97-2-d3bj2b

b97-2-d3bjatm

b97-2-d3zero2b

b97-2-d3zeroatm

b97-3

B97-3 Hyb-GGA Exchange-Correlation Functional

b97-d

b97-d3bj

b97-d3mbj

b97-gga1

B97-GGA1 GGA Exchange-Correlation Functional

b97-k

B97-K Hyb-GGA Exchange-Correlation Functional

b973c

B97-3c GGA-based 3C composite method with a TZ basis set, D3 and short-range basis set correction. (10.1063/1.5012601)

b97m-d3bj

b97m-v

B97M-V GGA Exchange-Correlation Functional

bb1k

BB1K Hyb-GGA Exchange-Correlation Functional

bhandh

BHandH Hyb-GGA Exchange-Correlation Functional

bhandhlyp

BHandHLYP Hyb-GGA Exchange-Correlation Functional

blyp

BLYP GGA Exchange-Correlation Functional

blyp-d3bj2b

blyp-d3bjatm

blyp-d3mbj2b

blyp-d3mbjatm

blyp-d3mzero2b

blyp-d3mzeroatm

blyp-d3zero2b

blyp-d3zeroatm

blyp-nl

BLYP GGA Exchange-Correlation Functional

bmk

BMK Hybrid Meta-GGA XC Functional for kinetics

bmk-d3bj2b

bmk-d3bjatm

bmk-d3zero2b

bmk-d3zeroatm

bop

BOP GGA Exchange-Correlation Functional

bop-d3bj2b

bop-d3bjatm

bop-d3zero2b

bop-d3zeroatm

bp86

BP86 GGA Exchange-Correlation Functional

bp86-d3bj2b

bp86-d3bjatm

bp86-d3mbj2b

bp86-d3mbjatm

bp86-d3mzero2b

bp86-d3mzeroatm

bp86-d3zero2b

bp86-d3zeroatm

bp86-nl

BP86 GGA Exchange-Correlation Functional

bp86-vwn

BP86 GGA XC Functional based on VWN5 corr. & more accurate ftilde value

cap0

CAP0 Hyb-GGA Exchange-Correlation Functional

dldf

Dispersionless Hybrid Meta-GGA XC Functional

dldf+d09

Dispersionless Hybrid Meta-GGA XC Functional

dldf+d10

Dispersionless Hybrid Meta-GGA XC Functional

edf1

EDF1 GGA Exchange-Correlation Functional

edf2

EDF2 Hyb-GGA Exchange-Correlation Functional

ft97

FT97 GGA Exchange-Correlation Functional

gam

GAM GGA Minessota Exchange-Correlation Functional

hcth120

HCTH120 GGA Exchange-Correlation Functional

hcth120-d3bj2b

hcth120-d3bjatm

hcth120-d3zero2b

hcth120-d3zeroatm

hcth147

HCTH147 GGA Exchange-Correlation Functional

hcth407

HCTH407 GGA Exchange-Correlation Functional

hcth407-d3bj2b

hcth407-d3bjatm

hcth407-d3zero2b

hcth407-d3zeroatm

hcth407p

HCTH407P GGA Exchange-Correlation Functional

hcth93

HCTH93 GGA Exchange-Correlation Functional

hcthp14

HCTHP14 GGA Exchange-Correlation Functional

hcthp76

HCTHP76 GGA Exchange-Correlation Functional

hf

Hartree–Fock theory

hf+d

hf-d3bj2b

hf-d3bjatm

hf-d3mbj2b

hf-d3mbjatm

hf-d3mzero2b

hf-d3mzeroatm

hf-d3zero2b

hf-d3zeroatm

hf-nl

Hartree–Fock theory

hf3c

Hartree Fock based 3C composite method with minimal basis set, gCP and D3(BJ)

hpbeint

HPBEINT Hyb-GGA Exchange-Correlation Functional

kmlyp

KMLYP Hyb-GGA Exchange-Correlation Functional

ksdt

KSDT Exchange-Correlation Functional

kt2

KT2 GGA Exchange-Correlation Functional

lda0

LDA0 Exchange-Correlation Functional

m05

M05 Meta-GGA XC Functional (10.1063/1.2126975)

m05-2x

Heavily Parameterized Hybrid M05-2X Meta-GGA XC Functional

m05-2x-d3zero2b

m05-2x-d3zeroatm

m05-d3zero2b

m05-d3zeroatm

m06

M06 Meta-GGA XC Functional (10.1007/s00214-007-0310-x)

m06-2x

Hybrid M06-2X Meta-GGA XC Functional (10.1007/s00214-007-0310-x)

m06-2x-d3zero2b

m06-2x-d3zeroatm

m06-d3zero2b

m06-d3zeroatm

m06-hf

Minnesota M06-HF Hybrid XC Functional (10.1021/jp066479k)

m06-hf-d3zero2b

m06-hf-d3zeroatm

m06-l

M06-L Meta-GGA XC Functional

m06-l-d3zero2b

m06-l-d3zeroatm

m08-hx

Minnesota M08-HX Hybrid XC Functional (10.1021/ct800246v)

m08-hx-d3zero2b

m08-hx-d3zeroatm

m08-so

Minnesota M08-SO Hybrid XC Functional (10.1021/ct800246v)

m11-l

M11-L Meta-GGA XC Functional

m11-l-d3bj2b

m11-l-d3bjatm

m11-l-d3zero2b

m11-l-d3zeroatm

mb3lyp-rc04

MB3LYP-RC04 Hyb-GGA Exchange-Correlation Functional

mgga_ms0

MGGA_MS0 Meta-GGA XC Functional

mgga_ms1

MGGA_MS1 Meta-GGA XC Functional

mgga_ms2

MGGA_MS2 Meta-GGA XC Functional

mgga_ms2h

MGGA_MS2h Hybrid Meta-GGA XC Functional

mgga_mvs

MGGA_MVS Meta-GGA XC Functional

mgga_mvsh

MGGA_MV2h Hybrid Meta-GGA XC Functional

mn12-l

MN12-L Meta-GGA XC Functional

mn12-l-d3bj2b

mn12-l-d3bjatm

mn12-l-d3zero2b

mn12-l-d3zeroatm

mn15

MN15 Hybrid Meta-GGA Exchange-Correlation Functional

mn15-d3bj2b

mn15-d3bjatm

mn15-l

MN15-L Meta-GGA XC Functional

mn15-l-d3zero2b

mn15-l-d3zeroatm

mohlyp

MOHLYP GGA Exchange-Correlation Functional

mohlyp2

MOHLYP2 GGA Exchange-Correlation Functional

mpw1b95

mPW1B95 Hyb-GGA Exchange-Correlation Functional

mpw1b95-d3bj2b

mpw1b95-d3bjatm

mpw1b95-d3zero2b

mpw1b95-d3zeroatm

mpw1k

mPW1K Hyb-GGA Exchange-Correlation Functional

mpw1lyp

mPW1LYP Hybrid GGA Exchange-Correlation Functional

mpw1lyp-d3zero2b

mpw1lyp-d3zeroatm

mpw1pbe

mPW1PBE Hybrid GGA Exchange-Correlation Functional

mpw1pw

mPW1PW Hyb-GGA Exchange-Correlation Functional

mpw1pw-d3bj2b

mpw1pw-d3bjatm

mpw1pw-d3zero2b

mpw1pw-d3zeroatm

mpw3lyp

mPW3LYP Hyb-GGA Exchange-Correlation Functional

mpw3pw

mPW3PW Hyb-GGA Exchange-Correlation Functional

mpwb1k

mPWB1K Hyb-GGA Exchange-Correlation Functional

mpwb1k-d3bj2b

mpwb1k-d3bjatm

mpwb1k-d3zero2b

mpwb1k-d3zeroatm

mpwlyp1m

mPWLYP1M Hyb-GGA Exchange-Correlation Functional

mpwlyp1w

mPWLYP1W GGA Exchange-Correlation Functional

mpwpw

mPWPW GGA Exchange-Correlation Functional

n12

N12 nonseparable GGA Exchange-Correlation Functional

n12-d3bj2b

n12-d3bjatm

n12-d3zero2b

n12-d3zeroatm

o3lyp

O3LYP Hyb-GGA Exchange-Correlation Functional

o3lyp-d3bj2b

o3lyp-d3bjatm

o3lyp-d3zero2b

o3lyp-d3zeroatm

oblyp-d

op-pbe

BP86 GGA Exchange-Correlation Functional

opbe-d

opwlyp-d

otpss-d

pbe

PBE GGA Exchange-Correlation Functional

pbe-d3bj2b

pbe-d3bjatm

pbe-d3mbj2b

pbe-d3mbjatm

pbe-d3mzero2b

pbe-d3mzeroatm

pbe-d3zero2b

pbe-d3zeroatm

pbe-nl

PBE GGA Exchange-Correlation Functional

pbe-sol

Perdew, Burke & Ernzerhof exchange (solids)

pbe-sol-d3bj2b

pbe-sol-d3bjatm

pbe-sol-d3zero2b

pbe-sol-d3zeroatm

pbe0

PBE0 Hyb-GGA Exchange-Correlation Functional

pbe0-13

PBE0-13 Hyb-GGA Exchange-Correlation Functional

pbe0-d3bj2b

pbe0-d3bjatm

pbe0-d3mbj2b

pbe0-d3mbjatm

pbe0-d3mzero2b

pbe0-d3mzeroatm

pbe0-d3zero2b

pbe0-d3zeroatm

pbe0-nl

PBE0-nl Hyb-GGA Exchange-Correlation Functional

pbe1w

PBE1W GGA Exchange-Correlation Functional

pbe50

PBE50 Hybrid GGA Exchange-Correlation Functional

pbeh3c

PBE Hybrid based 3C composite method with a small basis set, gCP and D3(BJ)

pbelyp1w

PBELYP1W GGA Exchange-Correlation Functional

pkzb

PKZB Meta-GGA XC Functional

pkzb-d3zero2b

pkzb-d3zeroatm

pw6b95

PW6B95 Hybrid Meta-GGA XC Functional

pw6b95-d3bj2b

pw6b95-d3bjatm

pw6b95-d3zero2b

pw6b95-d3zeroatm

pw86b95

PW86B95 Hyb-GGA Exchange-Correlation Functional

pw86pbe

PW86PBE GGA Exchange-Correlation Functional

pw91

PW91 GGA Exchange-Correlation Functional

pw91-d3bj2b

pw91-d3bjatm

pwb6k

PWB6K Hyb-GGA Exchange-Correlation Functional

pwb6k-d3bj2b

pwb6k-d3bjatm

pwb6k-d3zero2b

pwb6k-d3zeroatm

r2scan

r2SCAN Meta-GGA XC Functional (0.1021/acs.jpclett.0c02405)

r2scan0

R2SCAN0 Hyb-GGA Exchange-Correlation Functional

r2scan50

R2SCAN50 Hyb-GGA Exchange-Correlation Functional

r2scanh

R2SCANh Hyb-GGA Exchange-Correlation Functional

revb3lyp

revB3LYP Hyb-GGA Exchange-Correlation Functional

revm06-l

Revised M06-L Meta-GGA XC Functional (10.1073/pnas.1705670114)

revpbe

revPBE GGA Exchange-Correlation Functional

revpbe-d3bj2b

revpbe-d3bjatm

revpbe-d3zero2b

revpbe-d3zeroatm

revpbe-nl

revPBE GGA Exchange-Correlation Functional

revpbe0

revPBE0 Hybrid GGA Exchange-Correlation Functional

revpbe0-d3bj2b

revpbe0-d3bjatm

revpbe0-d3zero2b

revpbe0-d3zeroatm

revpbe0-nl

revPBE0 Hybrid GGA Exchange-Correlation Functional

revscan

Revised SCAN Meta-GGA XC Functional (10.1021/acs.jctc.8b00072)

revscan0

Revised SCAN0 Hybrid Meta-GGA XC Functional (10.1021/acs.jctc.8b00072)

revtpss

revised TPSS Meta-GGA XC Functional

revtpss-d3bj2b

revtpss-d3bjatm

revtpss-d3zero2b

revtpss-d3zeroatm

revtpss-nl

revised TPSS Meta-GGA XC Functional

revtpssh

revTPSSh Hyb-GGA Exchange-Correlation Functional

revtpssh-d3bj2b

revtpssh-d3bjatm

revtpssh-d3zero2b

revtpssh-d3zeroatm

rpbe

RPBE GGA Exchange-Correlation Functional

rpbe-d3bj2b

rpbe-d3bjatm

rpbe-d3zero2b

rpbe-d3zeroatm

sb98-1a

SB98-1a Hyb-GGA Exchange-Correlation Functional

sb98-1b

SB98-1b Hyb-GGA Exchange-Correlation Functional

sb98-1c

SB98-1c Hyb-GGA Exchange-Correlation Functional

sb98-2a

SB98-2a Hyb-GGA Exchange-Correlation Functional

sb98-2b

SB98-2b Hyb-GGA Exchange-Correlation Functional

sb98-2c

SB98-2c Hyb-GGA Exchange-Correlation Functional

scan

SCAN Meta-GGA XC Functional (10.1103/PhysRevLett.115.036402)

scan-d3bj2b

scan-d3bjatm

scan-d3zero2b

scan-d3zeroatm

scan0

SCAN0 Hybrid Meta-GGA XC Functional (10.1063/1.4940734)

sogga

SOGGA Exchange + PBE Correlation Functional

sogga11

SOGGA11 Exchange-Correlation Functional

sogga11-x

SOGGA11-X Hybrid Exchange-Correlation Functional

sogga11-x-d3bj2b

sogga11-x-d3bjatm

sogga11-x-d3zero2b

sogga11-x-d3zeroatm

spw92

Slater exchange

svwn

Slater exchange

t-hcth

Tau HCTH Meta-GGA XC Functional

t-hcth-d3bj2b

t-hcth-d3bjatm

t-hcth-d3zero2b

t-hcth-d3zeroatm

t-hcthh

Hybrid Tau HCTH Meta-GGA XC Functional

teter93

TETER93 Exchange-Correlation Functional

th-fc

TH-FC GGA Exchange-Correlation Functional

th-fcfo

TH-FCFO GGA Exchange-Correlation Functional

th-fco

TH-FCO GGA Exchange-Correlation Functional

th-fl

TH-FL GGA Exchange-Correlation Functional

th1

TH1 GGA Exchange-Correlation Functional

th2

TH2 GGA Exchange-Correlation Functional

th3

TH3 GGA Exchange-Correlation Functional

th4

TH4 GGA Exchange-Correlation Functional

tpss

TPSS Meta-GGA XC Functional

tpss-d3bj2b

tpss-d3bjatm

tpss-d3zero2b

tpss-d3zeroatm

tpss-nl

TPSS Meta-GGA XC Functional

tpssh

TPSSh Hyb-GGA Exchange-Correlation Functional

tpssh-d3bj2b

tpssh-d3bjatm

tpssh-d3zero2b

tpssh-d3zeroatm

tpssh-nl

TPSSh-nl Hyb-GGA Exchange-Correlation Functional

tpsslyp1w

TPSSLYP1W GGA Exchange-Correlation Functional

vsxc

VSXC Meta-GGA XC Functional

vv10

VV10 GGA Exchange-Correlation Functional

x1b95

X1B95 Hyb-GGA Exchange-Correlation Functional

x3lyp

X3LYP Hyb-GGA Exchange-Correlation Functional

x3lyp-d3bj2b

x3lyp-d3bjatm

x3lyp-d3zero2b

x3lyp-d3zeroatm

xb1k

XB1K Hyb-GGA Exchange-Correlation Functional

xlyp

XLYP GGA Exchange-Correlation Functional

xlyp-d3bj2b

xlyp-d3bjatm

xlyp-d3zero2b

xlyp-d3zeroatm

zlp

ZLP GGA Exchange-Correlation Functional

name

calls method in Stanton and Gauss’s CFOUR program [manual]

c4-scf

Hartree–Fock (HF)

c4-mp2

2nd-order Møller–Plesset perturbation theory (non-density-fitting) (MP2)

c4-mp3

3rd-order Møller–Plesset perturbation theory (MP3)

c4-mp4(sdq)

4th-order MP perturbation theory (MP4) less triples

c4-mp4

full MP4

c4-cc2

approximate coupled cluster singles and doubles (CC2)

c4-ccsd

coupled cluster singles and doubles (CCSD)

c4-cc3

approximate CC singles, doubles, and triples (CC3)

c4-ccsd(t)

CCSD with perturbative triples (CCSD(T))

c4-ccsdt

coupled cluster singles, doubles, and triples (CCSDT)

cfour

expert full control over cfour program

Examples:

>>> # [1] Analytic hf optimization
>>> optimize('hf')
>>> # [2] Finite difference mp5 optimization with gradient
>>> #     printed to output file
>>> e, wfn = opt('mp5', return_wfn='yes')
>>> wfn.gradient().print_out()
>>> # [3] Can automatically perform complete basis set extrapolations
>>> optimize('MP2/cc-pV([D,T]+d)Z')
>>> # [4] Can automatically perform delta corrections that include extrapolations
>>> # even with a user-defined extrapolation formula. See sample inputs named
>>> # cbs-xtpl* for more examples of this input style
>>> optimize("MP2/aug-cc-pv([d,t]+d)z + d:ccsd(t)/cc-pvdz", corl_scheme=myxtplfn_2)
>>> # [5] Get info like geometry, gradient, energy back after an
>>> #     optimization fails. Note that the energy and gradient
>>> #     correspond to the last optimization cycle, whereas the
>>> #     geometry (by default) is the anticipated *next* optimization step.
>>> try:
>>>     optimize('hf/cc-pvtz')
>>> except psi4.OptimizationConvergenceError as ex:
>>>     next_geom_coords_as_numpy_array = np.asarray(ex.wfn.molecule().geometry())
psi4.gradient(name[, molecule, return_wfn, func, dertype])[source]

Function complementary to optimize(). Carries out one gradient pass, deciding analytic or finite difference.

Returns:

Matrix – Total electronic gradient in Hartrees/Bohr.

Returns:

(Matrix, Wavefunction) – gradient and wavefunction when return_wfn specified.

Examples:

>>> # [1] Single-point dft gradient getting the gradient
>>> #     in file, core.Matrix, and np.array forms
>>> set gradient_write on
>>> G, wfn = gradient('b3lyp-d', return_wfn=True)
>>> wfn.gradient().print_out()
>>> np.array(G)