Geometry Optimization — `optimize()` and `gradient()`¶

Psi4 Native Gradient Methods
Psi4 Native DFT Gradient Methods (excepting double-hybrids)
CFOUR Interfaced Gradient Methods

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:

CURRENT ENERGY

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
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
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
m06-2x	Hybrid M06-2X Meta-GGA XC Functional
m06-2x-d3zero2b
m06-2x-d3zeroatm
m06-d3zero2b
m06-d3zeroatm
m06-hf	Minnesota M06-HF Hybrid XC Functional
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
m08-hx-d3zero2b
m08-hx-d3zeroatm
m08-so	Minnesota M08-SO Hybrid XC Functional
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
revb3lyp	revB3LYP Hyb-GGA Exchange-Correlation Functional
revm06-l	Revised M06-L Meta-GGA XC Functional
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
revscan0	Revised SCAN0 Hybrid Meta-GGA XC Functional
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
scan-d3bj2b
scan-d3bjatm
scan-d3zero2b
scan-d3zeroatm
scan0	SCAN0 Hybrid Meta-GGA XC Functional
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)

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

Geometry Optimization — optimize() and gradient()¶

Geometry Optimization — `optimize()` and `gradient()`¶