~ubuntu-branches/ubuntu/oneiric/mpqc/oneiric : revision 3.1.2

1

.TH MPQC 1 "18 Oct 2001" Version 2.0.0

2

.ad l

3

.nh

4

.SH NAME

5

mpqc \- The Massively Parallel Quantum Chemistry program (MPQC)

6

.SH SYNOPSIS

7

.B mpqc

8

[options] [filename]

9

.SH DESCRIPTION

10

MPQC computes the properties of molecules, \fIab initio\fP, on a wide variety of computer architectures.

11

.PP

12

It can compute closed shell and general restricted open-shell Hartree-Fock energies and gradients, second order open-shell perturbation theory (OPT2[2]) and Z-averaged perturbation theory (ZAPT2) energies, and second order closed shell Moeller-Plesset perturbation theory energies and gradients. It also includes methods for optimizing molecules in either Cartesian or internal coordinates.

13

.PP

14

MPQC is designed using object-oriented programming techniques and implemented in the C++ programming language.

15

.SH OPTIONS

16

.PP

17

MPQC can be given options followed by an optional input file name. If the input file name is not given, it will default to 'mpqc.in'. The following command line options are recognized:

18

.TP 8

19

.B -o

20

Gives the name of the output file. The default is the console.

21

.TP 8

22

.B -i

23

Convert a simple input file to an object oriented input file and write the result to the ouput. No calculations are done.

24

.TP 8

25

.B -messagegrp

26

A \fBParsedKeyVal\fP specification of a \fBMessageGrp\fP object. The default depends on how MPQC was compiled.

27

.TP 8

28

.B -memorygrp

29

A \fBParsedKeyVal\fP specification of a \fBMemoryGrp\fP object. The default depends on how MPQC was compiled.

30

.TP 8

31

.B -threadgrp

32

A \fBParsedKeyVal\fP specification of a \fBThreadGrp\fP object. The default depends on how MPQC was compiled.

33

.TP 8

34

.B "\fC-l\fP"

35

Sets a limit on the number of basis functions. The default is zero, which means an unlimited number of basis functions.

36

.TP 8

37

.B -W

38

Sets the working directory. The default is the current directory.

39

.TP 8

40

.B -c

41

Check the input and exit.

42

.TP 8

43

.B -v

44

Print the version number.

45

.TP 8

46

.B -w

47

Print the warranty information (there is no warranty).

48

.TP 8

49

.B -d

50

If a debugger object was given in the input, start the debugger running as soon as MPQC is started.

51

.TP 8

52

.B -h

53

Print a list of options.

54

.TP 8

55

.B -f

56

The name of an object-oriented input file. The default is \fCmpqc.in\fP. This cannot be used if another input file is specified. This option is deprecated, as both input file formats can be read by given the input file name on the command line without any option flags.

57

.PP

58

Some MPI environments do not pass the command line to slave programs, but supply it when MPI_Init is called. To make MPQC call MPI_Init on start-up, instead of when an \fBMPIMessageGrp\fP is created, name the executable mpqc-mpi.

59

.PP

60

.SH ENVIRONMENTAL VARIABLES

61

.PP

62

MPQC looks at four environmental variables to set up communication and find library files. Machine specific libraries and utilities to run programs in parallel might look at other environment variables as well. The four that apply on all platforms are:

63

.TP 8

64

.B SCLIBDIR

65

The name of the library directory.

66

.TP

67

.B MESSAGEGRP

68

A \fBParsedKeyVal\fP specification of a \fBMessageGrp\fP object. The default depends on how MPQC was compiled. See the \fBMessageGrp\fP class documentation for more information.

69

.TP 8

70

.B MEMORYGRP

71

A \fBParsedKeyVal\fP specification of a \fBMemoryGrp\fP object. The default depends on how MPQC was compiled and the \fBMessageGrp\fP in use.

72

.TP 8

73

.B THREADGRP

74

A \fBParsedKeyVal\fP specification of a \fBThreadGrp\fP object. The default depends on how MPQC was compiled.

75

.PP

76

By default, MPQC tries to find library files first in the \fClib\fP subdirectory of the installation directory and then the source code directory. If the library files cannot be found, MPQC must be notified of the new location with the environmental variable \fCSCLIBDIR\fP.

77

.PP

78

The other three keywords specify objects. This is done by giving a mini \fBParsedKeyVal\fP input in a string. The object is anonymous, that is, no keyword is associated with it. Here is an example:

79

.PP

80

.nf

81

82

setenv MESSAGEGRP '<\fBShmMessageGrp\fP>:(n = 4)'

83

84

.fi

85

.PP

86

.SH SHARED MEMORY MULTIPROCESSOR WITH SYSV IPC

87

.PP

88

By default, MPQC will run on only one CPU. To specify more, you can give a \fBShmMessageGrp\fP object on the command line. The following would run mpqc in four processes:

89

.PP

90

.nf

91

92

mpqc -messagegrp '<\fBShmMessageGrp\fP>:(n = 4)' input_file

93

94

.fi

95

.PP

96

Alternately, the \fBShmMessageGrp\fP object can be given as an environmental variable:

97

.PP

98

.nf

99

100

setenv MESSAGEGRP '<\fBShmMessageGrp\fP>:(n = 4)'

101

mpqc input_file

102

103

.fi

104

.PP

105

If MPQC should unexpectedly die, shared memory segments and semaphores will be left on the machine. These should be promptly cleaned up or other jobs may be prevented from running successfully. To see if you have any of these resources allocated, use the \fCipcs\fP command. The output will look something like:

106

.PP

107

.nf

108

109

IPC status from /dev/kmem as of Wed Mar 13 14:42:18 1996

110

T ID KEY MODE OWNER GROUP

111

Message Queues:

112

Shared Memory:

113

m 288800 0x00000000 --rw------- cljanss user

114

Semaphores:

115

s 390 0x00000000 --ra------- cljanss user

116

s 391 0x00000000 --ra------- cljanss user

117

118

.fi

119

.PP

120

To remove the IPC resources used by \fCcljanss\fP in the above example on IRIX, type:

121

.PP

122

.nf

123

124

ipcrm -m 288800

125

ipcrm -s 390

126

ipcrm -s 391

127

128

.fi

129

.PP

130

And on Linux, type:

131

.PP

132

.nf

133

134

ipcrm shm 288800

135

ipcrm sem 390

136

ipcrm sem 391

137

138

.fi

139

.PP

140

.SH SHARED MEMORY MULTIPROCESSOR WITH POSIX THREADS

141

.PP

142

By default, MPQC will run with only one thread. To specify more, you can give a \fBPthreadThreadGrp\fP object on the command line. MPQC is not parallelized to as large an extent with threads as it is with the more conventional distributed memory model, so you might not get the best performance using this technique. On the other the memory overhead is lower and no interprocess communication is needed.

143

.PP

144

The following would run MPQC in four threads:

145

.PP

146

.nf

147

148

mpqc -threadgrp '<\fBPthreadThreadGrp\fP>:(num_threads = 4)' input_file

149

150

.fi

151

.PP

152

Alternately, the \fBPthreadThreadGrp\fP object can be given as an environmental variable:

153

.PP

154

.nf

155

156

setenv THREADGRP '<\fBPthreadThreadGrp\fP>:(n = 4)'

157

mpqc input_file

158

159

.fi

160

.PP

161

.SH SHARED OR DISTRIBUTED MEMORY MULTIPROCESSOR WITH MPI

162

.PP

163

A \fBMPIMessageGrp\fP object is used to run using MPI. The number of nodes used is determined by the MPI run-time and is not specified as input data to \fBMPIMessageGrp\fP.

164

.PP

165

.nf

166

167

mpqc -messagegrp '<\fBMPIMessageGrp\fP>:()' input_file

168

169

.fi

170

.PP

171

Alternately, the \fBMPIMessageGrp\fP object can be given as an environmental variable:

172

.PP

173

.nf

174

175

setenv MESSAGEGRP '<\fBMPIMessageGrp\fP>:()'

176

mpqc input_file

177

178

.fi

179

.PP

180

Usually, a special command is needed to start MPI jobs; typically it is named \fCmpirun\fP.

181

.PP

182

.SH INPUT

183

MPQC supports two input formats. The primary input is an object oriented format which gives users access to all of MPQC's options. The second format allows access to a subset of MPQC's capabilities, but is more intuitive and easier to learn. New users are advised to start with the simplified format. MPQC can be used to convert the simplified format to the full object-oriented format with the \fC-i\fP option.

184

.PP

185

.SH Simple Input

186

The simple input format consists of keywords followed by a ':' followed by a value. The keywords are case sensitive. The values might be modified by options found in parenthesis. For example, the following input performs an optimization of water using density functional theory with the B3LYP exchange-correlation functional:

187

.PP

188

.nf

189

190

% B3LYP optimization of water

191

optimize: yes

192

method: KS (xc = B3LYP)

193

basis: 3-21G*

194

molecule:

195

O 0.172 0.000 0.000

196

H 0.745 0.000 0.754

197

H 0.745 0.000 -0.754

198

199

.fi

200

.PP

201

Comments begin with a \fC%\fP and continue to the end of the line. Basis set names containing special characters, such as a space or parentheses, must be quoted inside a pair of double quotes. The accepted keywords are:

202

.PP

203

.IP "\fCmolecule\fP" 1c

204

Gives the atoms types and coordinates. The following options can be used

205

.PP

206

207

.IP "\fCbohr\fP" 1c

208

The coordinates are given in Bohr.

209

.IP "\fCangstrom\fP" 1c

210

The coordinates are given in Angstroms.

211

.IP "\fCcharge\fP" 1c

212

This option can be given after an 'element x y z' quadruple. This will override the charge on the atom. For example, \fC(charge = 0)\fP can be given for the ghost atoms in a counterpoise correction calculation.

213

.PP

214

.IP "\fCmultiplicity\fP" 1c

215

Gives the multiplicity of the molecule. The default is \fC1\fP.

216

.PP

217

.IP "\fCoptimize\fP" 1c

218

If \fCyes\fP, then an optimization will be performed. The default is \fCno\fP. The following options can be given.

219

.PP

220

221

.IP "\fCcartesian\fP" 1c

222

Use Cartesian coordinates.

223

.IP "\fCinternal\fP" 1c

224

Use internal coordinates.

225

.IP "\fCredundant\fP" 1c

226

Use redundant internal coordinates.

227

.PP

228

.IP "\fCgradient\fP" 1c

229

If \fCyes\fP, then a gradient calculation will be performed. The default is \fCno\fP.

230

.PP

231

.IP "\fCfrequencies\fP" 1c

232

If \fCyes\fP, then the frequencies will be obtained. The default is \fCno\fP.

233

.PP

234

.IP "\fCcharge\fP" 1c

235

Specificies the charge on the molecule. The default is \fC0\fP.

236

.PP

237

.IP "\fCmethod\fP" 1c

238

Specifices the method. There is no default and the possible values are:

239

.PP

240

.IP "\fCHF\fP" 1c

241

Hartree-Fock. Unrestricted HF is used if \fCmultiplicity\fP > 1

242

.IP "\fCRHF\fP" 1c

243

Restricted Hartree-Fock.

244

.IP "\fCUHF\fP" 1c

245

Unrestricted Hartree-Fock.

246

.IP "\fCKS\fP" 1c

247

Kohn-Sham. Unrestricted KS is used if \fCmultiplicity\fP > 1

248

.IP "\fCRKS\fP" 1c

249

Restricted Kohn-Sham.

250

.IP "\fCUKS\fP" 1c

251

Unrestricted Kohn-Sham.

252

.IP "\fCMP2\fP" 1c

253

Second order Moeller-Plesset perturbation theory. Only available for \fCmultiplicity\fP = 1.

254

.IP "\fCZAPT2\fP" 1c

255

Z-averaged perturbation theory. Only available for \fCmultiplicity\fP > 1. No gradient, optimization, or frequencies are possible.

256

.PP

257

The following options are valid with the \fCKS\fP, \fCRKS\fP, and \fCUKS\fP methods:

258

.PP

259

260

.IP "\fCgrid\fP" 1c

261

Specifies the grid to be used for numerical integrations. The following values can be given:

262

.IP "\fCxcoarse\fP" 1c

263

264

.IP "\fCcoarse\fP" 1c

265

266

.IP "\fCmedium\fP" 1c

267

268

.IP "\fCfine\fP" 1c

269

270

.IP "\fCxfine\fP" 1c

271

272

.IP "\fCultrafine\fP" 1c

273

274

.IP "\fCxc\fP" 1c

275

Specifies the exchange-correlation functional. There is no default. See the table in the \fBStdDenFunctional\fP class documentation for the possible values.

276

.PP

277

.IP "\fCbasis\fP" 1c

278

Specifies the basis set. There is no default. See the table in the \fBGaussianBasisSet\fP class documentation for the available basis sets.

279

.PP

280

.IP "\fCrestart\fP" 1c

281

Set to \fCyes\fP to restart an optimization. The default is \fCno\fP.

282

.PP

283

.IP "\fCcheckpoint\fP" 1c

284

Set to \fCno\fP to not save checkpoint files during an optimization. The default is \fCyes\fP.

285

.PP

286

.IP "\fCsymmetry\fP" 1c

287

Specifices the Schoenflies symbol of the point group of the molecule. The default is \fCauto\fP, which will cause to program to find the highest order Abelian subgroup of the molecule.

288

.PP

289

.IP "\fCdocc\fP" 1c

290

Gives the number of doubly occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be \fCauto\fP. The method must be restricted.

291

.PP

292

.IP "\fCsocc\fP" 1c

293

Gives the number of single occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be \fCauto\fP. The method must be restricted.

294

.PP

295

.IP "\fCalpha\fP" 1c

296

Gives the number of alpha occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be \fCauto\fP. The method must be unrestricted.

297

.PP

298

.IP "\fCbeta\fP" 1c

299

Gives the number of beta occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be \fCauto\fP. The method must be unrestricted.

300

.PP

301

.IP "\fCfrozen_docc\fP" 1c

302

Gives the number of frozen core orbitals. Can be either a single integer or a parenthesized list giving the frozen core orbitals in each irreducible representation. In the latter case the symmetry must be given and not be \fCauto\fP.

303

.PP

304

.IP "\fCfrozen_uocc\fP" 1c

305

Gives the number of frozen virtual orbitals. Can be either a single integer or a parenthesized list giving the frozen virtual orbitals in each irreducible representation. In the latter case the symmetry must be given and not be \fCauto\fP.

306

.PP

307

.SH Object-Oriented Input

308

MPQC is an object-oriented program that directly allows the user to specify objects that MPQC then manipulates to obtain energies, properties, etc. This makes the input very flexible, but very complex. However, most calculations should be quite similar to the one of the examples given later in this chapter. The best way to get started is to use one of the example input files and modify it to meet your needs.

309

.PP

310

MPQC starts off by creating a \fBParsedKeyVal\fP object that parses the input file specified on the command line. The format of the input file is documented in . It is basically a free format input that associates keywords and logical groupings of keywords with values. The values can be scalars, arrays, or objects.

311

.PP

312

The keywords recognized by MPQC begin with the mpqc prefix. That is, they must be nested between an \fCmpqc:(\fP and a \fC)\fP. Alternately, each keyword can be individually prefixed by \fCmpqc:\fP. The primary keywords are given below. Some of the keywords specify objects, in which case the object will require more \fBParsedKeyVal\fP input. These objects are created from the input by using their \fBParsedKeyVal\fP constructors. These constructors are documented with the source code documentation for the class.

313

.PP

314

.IP "\fCmole\fP" 1c

315

This is the most important keyword for MPQC. It specifies the \fBMolecularEnergy\fP object. This is an object that knows how to compute the energy of a molecule. The specializations of \fBMolecularEnergy\fP that are most commonly used are CLKS, HSOSKS, UKS, \fBCLHF\fP, \fBHSOSHF\fP, UHF, and \fBMBPT2\fP.

316

.PP

317

.IP "\fCopt\fP" 1c

318

This keyword must be specified for optimizations. It specifies an \fBOptimize\fP object. Usually, \fBQNewtonOpt\fP is best for finding minima and \fBEFCOpt\fP is best for transition states.

319

.PP

320

.IP "\fCfreq\fP" 1c

321

This keyword must be specified to compute frequencies. It specifies a \fBMolecularFrequencies\fP object.

322

.PP

323

.IP "\fCthread\fP" 1c

324

This specifies an object of type \fBThreadGrp\fP that can be used to advantage on shared-memory multiprocessor machines for certain types of calculations. This keyword can be overridden by giving the \fBThreadGrp\fP in the environment or command line. See the section on running MPQC for more information.

325

.PP

326

.IP "\fCcheckpoint\fP" 1c

327

The value of this keyword is boolean. If true, then optimizations will be checkpointed after each iteration. The checkpoint file suffice is \fC.ckpt\fP. The default is to checkpoint.

328

.PP

329

.IP "\fCsavestate\fP" 1c

330

The value of this keyword is boolean. If true, then the states of the optimizer and wavefunction objects will be saved after the calculation completes. The output file suffix is \fC.wfn\fP. The default is to save state.

331

.PP

332

.IP "\fCrestart\fP" 1c

333

The value of this keyword is boolean. If true, mpqc will attempt to restart the calculation. If the checkpoint file is not found, the calculation will continue as if the value were false. The default is true.

334

.PP

335

.IP "\fCrestart_file\fP" 1c

336

This gives the name of a file from which restart information is read. If the file name ends in \fC.wfn\fP the \fBMolecularEnergy\fP object will be restored. Otherwise, the \fBOptimize\fP object will be restored. The default file name is formed by appending \fC.ckpt\fP to the input file name with the extension removed.

337

.PP

338

.IP "\fCdo_energy\fP" 1c

339

The value of this keyword is boolean. If true a single point energy calculation will be done for the \fBMolecularEnergy\fP object given with the mole keyword. The default is true.

340

.PP

341

.IP "\fCdo_gradient\fP" 1c

342

The value of this keyword is boolean. If true a single point gradient calculation will be done for the \fBMolecularEnergy\fP object given with the mole keyword. The default is false.

343

.PP

344

.IP "\fCoptimize\fP" 1c

345

The value of this keyword is boolean. If true and the opt keyword was set to a valid value, then an optimization will be performed. The default is true.

346

.PP

347

.IP "\fCwrite_pdb\fP" 1c

348

The value of this keyword is boolean. If true a PDB file with the molecular coordinates will be written.

349

.PP

350

.IP "\fCfilename\fP" 1c

351

The value of this keyword is a string that gives a name from which checkpoint and other filenames are constructed. The default is the basename of the input file.

352

.PP

353

.IP "\fCprint_timings\fP" 1c

354

If this is true, timing information is printed at the end of the run. The default is true.

355

.PP

356

There are also some utility keywords that tell mpqc some technical details about how to do the calculation:

357

.IP "\fCdebug\fP" 1c

358

This optional keyword gives a \fBDebugger\fP object which can used to help find the problem if MPQC encounters a catastrophic error.

359

.IP "\fCmatrixkit\fP" 1c

360

This optional keyword gives a \fBSCMatrixKit\fP specialization which is used to produce matrices of the desired type. The default is a \fBReplSCMatrixKit\fP which replicates matrices on all of the nodes. Other choices are not thoroughly tested.

361

.PP

362

.SH EXAMPLES

363

.PP

364

This example input does a Hartree-Fock calculation on water. Following is the entire input, followed by a breakdown with descriptions.

365

.PP

366

.nf

367

368

% This input does a Hartree-Fock calculation on water.

369

molecule<\fBMolecule\fP>: (

370

symmetry = C2V

371

unit = angstrom

372

{ atoms geometry } = {

373

O [ 0.00000000 0.00000000 0.37000000 ]

374

H [ 0.78000000 0.00000000 -0.18000000 ]

375

H [ -0.78000000 0.00000000 -0.18000000 ]

376

}

377

)

378

basis<\fBGaussianBasisSet\fP>: (

379

name = 'STO-3G'

380

molecule = $:molecule

381

)

382

mpqc: (

383

mole<\fBCLHF\fP>: (

384

molecule = $:molecule

385

basis = $:basis

386

)

387

)

388

389

.fi

390

.PP

391

We start with a descriptive comment. Comments begin with a \fC%\fP. Everything from the \fC%\fP to the end of the line is ignored.

392

.PP

393

.nf

394

395

% This input does a Hartree-Fock calculation on water.

396

397

.fi

398

.PP

399

Now lets set up a \fBMolecule\fP object. The name of the object comes first, it is \fCmolecule\fP. Then, in angle brackets, comes the type of the molecule, which is the class \fBMolecule\fP. The keyword and class name are followed by a \fC:\fP and then several pieces of input grouped between a pair of matching parentheses. These parentheses contain the information that will be given to \fBMolecule\fP \fBKeyVal\fP constructor.

400

.PP

401

.nf

402

403

molecule<\fBMolecule\fP>: (

404

405

.fi

406

.PP

407

The point group of the molecule is needed. This is done by assigning \fCsymmetry\fP to a case insensitive Schoenflies symbol that is used to initialize a \fBPointGroup\fP object. An Abelian point group should be used.

408

.PP

409

.nf

410

411

symmetry = C2V

412

413

.fi

414

.PP

415

The default unit for the Cartesian coordinates is Bohr. You can specify other units by assigned \fCunit\fP to a string that will be used to initialize a \fBUnits\fP object.

416

.PP

417

.nf

418

419

unit = angstrom

420

421

.fi

422

.PP

423

Finally, the atoms and coordinates are given. This can be given in the shorthand table syntax shown below. The headings of the table are the keywords between the first pair of brackets. These are followed by an \fC=\fP and another pair of brackets that contain the data. The first datum is assigned to the first element of the array that corresponds to the first heading, \fCatom\fP. The second datum is assigned to the first element of the array associated with the second heading, \fCgeometry\fP, and so on. Here the second datum is actually a vector: the x, y and z coordinates of the first atom.

424

.PP

425

.nf

426

427

{ atoms geometry } = {

428

O [ 0.00000000 0.00000000 0.37000000 ]

429

H [ 0.78000000 0.00000000 -0.18000000 ]

430

H [ -0.78000000 0.00000000 -0.18000000 ]

431

}

432

)

433

434

.fi

435

.PP

436

Next, a basis set object is given.

437

.PP

438

.nf

439

440

basis<\fBGaussianBasisSet\fP>: (

441

name = 'STO-3G'

442

molecule = $:molecule

443

)

444

445

.fi

446

.PP

447

Now we will give the main body of input. All the subsequent keywords will be grouped in the \fCmpqc\fP section of the input (that is, each keyword will be prefixed with \fCmpqc:\fP).

448

.PP

449

.nf

450

451

mpqc: (

452

453

.fi

454

.PP

455

Next we give the \fCmole\fP keyword which provides a specialization of the \fBMolecularEnergy\fP class. In this case we will do a closed-shell Hartree-Fock calculation. That is done with an object of type \fBCLHF\fP. The keywords that \fBCLHF\fP accepts are given with the documentation for the \fBCLHF\fP class, usually in the description of the \fCconst RefKeyVal&\fP constructor for the class. Also with the \fBCLHF\fP documentation is a list of parent classes. Each of the parent classes may also have input. This input is included with the rest of the input for the child class.

456

.PP

457

.nf

458

459

mole<\fBCLHF\fP>: (

460

461

.fi

462

.PP

463

The next line specifies the molecule to be used. There are two things to note, first that this is actually a reference to complete molecule specification elsewhere in the input file. The \fC$\fP indicates that this is a reference and the keyword following the \fC$\fP is the actual location of the molecule. The \fC:\fP in front of the keyword means that the keyword is not relative to the current location in the input, but rather relative to the root of the tree of keywords. Thus, this line grabs the molecule that was specified above. The molecule object could have been placed here, but frequently it is necessary that several objects refer to the exact same object and this can only be done using references.

464

.PP

465

The second point is that if you look at the documentation for \fBCLHF\fP, you will see that it doesn't read \fCmolecule\fP keyword. However, if you follow its parent classes up to \fBMolecularEnergy\fP, you'll find that \fCmolecule\fP is indeed read.

466

.PP

467

.nf

468

469

molecule = $:molecule

470

471

.fi

472

.PP

473

Just as we gave \fCmolecule\fP, specify the basis set with the \fCbasis\fP keyword as follows:

474

.PP

475

.nf

476

477

basis = $:basis

478

479

.fi

480

.PP

481

Now we close off the parentheses we opened above and we are finished.

482

.PP

483

.nf

484

485

)

486

)

487

488

.fi

489

.PP

490

.SH "Sample Object-Oriented Input Files"

491

.PP

492

The easiest way to get started with mpqc is to start with one of sample inputs that most nearly matches your problem. All of the samples inputs shown here can be found in the directory \fCsrc/bin/mpqc/samples\fP.

493

.PP

494

.TP

495

496

.TP

497

498

.TP

499

500

.TP

501

502

.TP

503

504

.TP

505

506

.TP

507

508

.TP

509

510

.TP

511

512

.TP

513

514

.TP

515

516

.PP

517

.SS "Hartree-Fock Energy"

518

.PP

519

The following input will compute the Hartree-Fock energy of water.

520

.PP

521

.nf

522

523

% emacs should use -*- \fBKeyVal\fP -*- mode

524

% molecule specification

525

molecule<\fBMolecule\fP>: (

526

symmetry = C2V

527

unit = angstrom

528

{ atoms geometry } = {

529

O [ 0.00000000 0.00000000 0.37000000 ]

530

H [ 0.78000000 0.00000000 -0.18000000 ]

531

H [ -0.78000000 0.00000000 -0.18000000 ]

532

}

533

)

534

% basis set specification

535

basis<\fBGaussianBasisSet\fP>: (

536

name = 'STO-3G'

537

molecule = $:molecule

538

)

539

mpqc: (

540

checkpoint = no

541

savestate = no

542

% method for computing the molecule's energy

543

mole<\fBCLHF\fP>: (

544

molecule = $:molecule

545

basis = $:basis

546

memory = 16000000

547

)

548

)

549

550

.fi

551

.PP

552

.SS "MP2 Energy"

553

.PP

554

The following input will compute the MP2 energy of water.

555

.PP

556

.nf

557

558

% emacs should use -*- \fBKeyVal\fP -*- mode

559

% molecule specification

560

molecule<\fBMolecule\fP>: (

561

symmetry = C2V

562

unit = angstrom

563

{ atoms geometry } = {

564

O [ 0.00000000 0.00000000 0.37000000 ]

565

H [ 0.78000000 0.00000000 -0.18000000 ]

566

H [ -0.78000000 0.00000000 -0.18000000 ]

567

}

568

)

569

% basis set specification

570

basis<\fBGaussianBasisSet\fP>: (

571

name = 'STO-3G'

572

molecule = $:molecule

573

)

574

mpqc: (

575

checkpoint = no

576

savestate = no

577

% method for computing the molecule's energy

578

mole<\fBMBPT2\fP>: (

579

molecule = $:molecule

580

basis = $:basis

581

memory = 16000000

582

% reference wavefunction

583

reference<\fBCLHF\fP>: (

584

molecule = $:molecule

585

basis = $:basis

586

memory = 16000000

587

)

588

)

589

)

590

591

.fi

592

.PP

593

.SS "Hartree-Fock Optimization"

594

.PP

595

The following input will optimize the geometry of water using the quasi-Newton method.

596

.PP

597

.nf

598

599

% emacs should use -*- \fBKeyVal\fP -*- mode

600

% molecule specification

601

molecule<\fBMolecule\fP>: (

602

symmetry = C2V

603

unit = angstrom

604

{ atoms geometry } = {

605

O [ 0.00000000 0.00000000 0.37000000 ]

606

H [ 0.78000000 0.00000000 -0.18000000 ]

607

H [ -0.78000000 0.00000000 -0.18000000 ]

608

}

609

)

610

% basis set specification

611

basis<\fBGaussianBasisSet\fP>: (

612

name = '6-31G*'

613

molecule = $:molecule

614

)

615

mpqc: (

616

checkpoint = no

617

savestate = no

618

% molecular coordinates for optimization

619

coor<\fBSymmMolecularCoor\fP>: (

620

molecule = $:molecule

621

generator<\fBIntCoorGen\fP>: (

622

molecule = $:molecule

623

)

624

)

625

% method for computing the molecule's energy

626

mole<\fBCLHF\fP>: (

627

molecule = $:molecule

628

basis = $:basis

629

coor = $..:coor

630

memory = 16000000

631

)

632

% optimizer object for the molecular geometry

633

opt<\fBQNewtonOpt\fP>: (

634

function = $..:mole

635

update<\fBBFGSUpdate\fP>: ()

636

convergence<MolEnergyConvergence>: (

637

cartesian = yes

638

energy = $..:..:mole

639

)

640

)

641

)

642

643

.fi

644

.PP

645

.SS "Optimization with a Computed Guess Hessian"

646

.PP

647

The following input will optimize the geometry of water using the quasi-Newton method. The guess Hessian will be computed at a lower level of theory.

648

.PP

649

.nf

650

651

% emacs should use -*- \fBKeyVal\fP -*- mode

652

% molecule specification

653

molecule<\fBMolecule\fP>: (

654

symmetry = C2V

655

unit = angstrom

656

{ atoms geometry } = {

657

O [ 0.00000000 0.00000000 0.37000000 ]

658

H [ 0.78000000 0.00000000 -0.18000000 ]

659

H [ -0.78000000 0.00000000 -0.18000000 ]

660

}

661

)

662

% basis set specification

663

basis<\fBGaussianBasisSet\fP>: (

664

name = '6-31G*'

665

molecule = $:molecule

666

)

667

mpqc: (

668

checkpoint = no

669

savestate = no

670

% molecular coordinates for optimization

671

coor<\fBSymmMolecularCoor\fP>: (

672

molecule = $:molecule

673

generator<\fBIntCoorGen\fP>: (

674

molecule = $:molecule

675

)

676

)

677

% method for computing the molecule's energy

678

mole<\fBCLHF\fP>: (

679

molecule = $:molecule

680

basis = $:basis

681

coor = $..:coor

682

memory = 16000000

683

guess_hessian<\fBFinDispMolecularHessian\fP>: (

684

molecule = $:molecule

685

only_totally_symmetric = yes

686

eliminate_cubic_terms = no

687

checkpoint = no

688

energy<\fBCLHF\fP>: (

689

molecule = $:molecule

690

memory = 16000000

691

basis<\fBGaussianBasisSet\fP>: (

692

name = '3-21G'

693

molecule = $:molecule

694

)

695

)

696

)

697

)

698

% optimizer object for the molecular geometry

699

opt<\fBQNewtonOpt\fP>: (

700

function = $..:mole

701

update<\fBBFGSUpdate\fP>: ()

702

convergence<MolEnergyConvergence>: (

703

cartesian = yes

704

energy = $..:..:mole

705

)

706

)

707

)

708

709

.fi

710

.PP

711

.SS "Optimization Using Newton's Method"

712

.PP

713

The following input will optimize the geometry of water using the Newton's method. The Hessian will be computed at each step in the optimization. However, Hessian recomputation is usually not worth the cost; try using the computed Hessian as a guess Hessian for a quasi-Newton method before resorting to a Newton optimization.

714

.PP

715

.nf

716

717

% Emacs should use -*- \fBKeyVal\fP -*- mode

718

% molecule specification

719

molecule<\fBMolecule\fP>: (

720

symmetry = c2v

721

unit = angstrom

722

{ atoms geometry } = {

723

O [ 0.00000000 0.00000000 0.36937294 ]

724

H [ 0.78397590 0.00000000 -0.18468647 ]

725

H [ -0.78397590 0.00000000 -0.18468647 ]

726

}

727

)

728

% basis set specification

729

basis<\fBGaussianBasisSet\fP>: (

730

name = '3-21G'

731

molecule = $:molecule

732

)

733

mpqc: (

734

checkpoint = no

735

savestate = no

736

restart = no

737

% molecular coordinates for optimization

738

coor<\fBSymmMolecularCoor\fP>: (

739

molecule = $:molecule

740

generator<\fBIntCoorGen\fP>: (

741

molecule = $:molecule

742

)

743

)

744

do_energy = no

745

do_gradient = no

746

% method for computing the molecule's energy

747

mole<\fBCLHF\fP>: (

748

molecule = $:molecule

749

basis = $:basis

750

memory = 16000000

751

coor = $..:coor

752

guess_wavefunction<\fBCLHF\fP>: (

753

molecule = $:molecule

754

total_charge = 0

755

basis<\fBGaussianBasisSet\fP>: (

756

molecule = $:molecule

757

name = 'STO-3G'

758

)

759

memory = 16000000

760

)

761

hessian<\fBFinDispMolecularHessian\fP>: (

762

only_totally_symmetric = yes

763

eliminate_cubic_terms = no

764

checkpoint = no

765

)

766

)

767

optimize = yes

768

% optimizer object for the molecular geometry

769

opt<NewtonOpt>: (

770

print_hessian = yes

771

max_iterations = 20

772

function = $..:mole

773

convergence<MolEnergyConvergence>: (

774

cartesian = yes

775

energy = $..:..:mole

776

)

777

)

778

)

779

780

.fi

781

.PP

782

.SS "Hartree-Fock Frequencies"

783

.PP

784

The following input will compute Hartree-Fock frequencies by finite displacements. A thermodynamic analysis will also be performed. If optimization input is also provided, then the optimization will be run first, then the frequencies.

785

.PP

786

.nf

787

788

% emacs should use -*- \fBKeyVal\fP -*- mode

789

% molecule specification

790

molecule<\fBMolecule\fP>: (

791

symmetry = C1

792

{ atoms geometry } = {

793

O [ 0.0000000000 0.0000000000 0.8072934188 ]

794

H [ 1.4325589285 0.0000000000 -0.3941980761 ]

795

H [ -1.4325589285 0.0000000000 -0.3941980761 ]

796

}

797

)

798

% basis set specification

799

basis<\fBGaussianBasisSet\fP>: (

800

name = 'STO-3G'

801

molecule = $:molecule

802

)

803

mpqc: (

804

checkpoint = no

805

savestate = no

806

% method for computing the molecule's energy

807

mole<\fBCLHF\fP>: (

808

molecule = $:molecule

809

basis = $:basis

810

memory = 16000000

811

)

812

% vibrational frequency input

813

freq<\fBMolecularFrequencies\fP>: (

814

molecule = $:molecule

815

)

816

)

817

818

.fi

819

.PP

820

.SS "Giving Coordinates and a Guess Hessian"

821

.PP

822

The following example shows several features that are really independent. The variable coordinates are explicitly given, rather than generated automatically. This is especially useful when a guess Hessian is to be provided, as it is here. This Hessian, as given by the user, is not complete and the \fBQNewtonOpt\fP object will fill in the missing values using a guess the Hessian provided by the \fBMolecularEnergy\fP object. Also, fixed coordinates are given in this sample input.

823

.PP

824

.nf

825

826

% emacs should use -*- \fBKeyVal\fP -*- mode

827

% molecule specification

828

molecule<\fBMolecule\fP>: (

829

symmetry = C1

830

{ atoms geometry } = {

831

H [ 0.088 2.006 1.438 ]

832

O [ 0.123 3.193 0.000 ]

833

H [ 0.088 2.006 -1.438 ]

834

O [ 4.502 5.955 -0.000 ]

835

H [ 2.917 4.963 -0.000 ]

836

H [ 3.812 7.691 -0.000 ]

837

}

838

)

839

% basis set specification

840

basis<\fBGaussianBasisSet\fP>: (

841

name = 'STO-3G'

842

molecule = $:molecule

843

)

844

mpqc: (

845

checkpoint = no

846

savestate = no

847

% method for computing the molecule's energy

848

mole<\fBCLHF\fP>: (

849

molecule = $:molecule

850

basis = $:basis

851

coor = $..:coor

852

memory = 16000000

853

)

854

% molecular coordinates for optimization

855

coor<\fBSymmMolecularCoor\fP>: (

856

molecule = $:molecule

857

generator<\fBIntCoorGen\fP>: (

858

molecule = $:molecule

859

extra_bonds = [ 2 5 ]

860

)

861

% use these instead of generated coordinates

862

variable<\fBSetIntCoor\fP>: [

863

<\fBStreSimpleCo\fP>:( atoms = [ 2 5 ] )

864

<\fBBendSimpleCo\fP>:( atoms = [ 2 5 4 ] )

865

<OutSimpleCo>: ( atoms = [ 5 2 1 3 ] )

866

<\fBSumIntCoor\fP>: (

867

coor: [

868

<\fBStreSimpleCo\fP>:( atoms = [ 1 2 ] )

869

<\fBStreSimpleCo\fP>:( atoms = [ 2 3 ] )

870

]

871

coef = [ 1.0 1.0 ]

872

)

873

<\fBSumIntCoor\fP>: (

874

coor: [

875

<\fBStreSimpleCo\fP>:( atoms = [ 4 5 ] )

876

<\fBStreSimpleCo\fP>:( atoms = [ 4 6 ] )

877

]

878

coef = [ 1.0 1.0 ]

879

)

880

<\fBBendSimpleCo\fP>:( atoms = [ 1 2 3 ] )

881

<\fBBendSimpleCo\fP>:( atoms = [ 5 4 6 ] )

882

]

883

% these are fixed by symmetry anyway,

884

fixed<\fBSetIntCoor\fP>: [

885

<\fBSumIntCoor\fP>: (

886

coor: [

887

<\fBStreSimpleCo\fP>:( atoms = [ 1 2 ] )

888

<\fBStreSimpleCo\fP>:( atoms = [ 2 3 ] )

889

]

890

coef = [ 1.0 -1.0 ]

891

)

892

<\fBSumIntCoor\fP>: (

893

coor: [

894

<\fBStreSimpleCo\fP>:( atoms = [ 4 5 ] )

895

<\fBStreSimpleCo\fP>:( atoms = [ 4 6 ] )

896

]

897

coef = [ 1.0 -1.0 ]

898

)

899

<\fBTorsSimpleCo\fP>:( atoms = [ 2 5 4 6] )

900

<OutSimpleCo>:( atoms = [ 3 2 6 4 ] )

901

<OutSimpleCo>:( atoms = [ 1 2 6 4 ] )

902

]

903

)

904

% optimizer object for the molecular geometry

905

opt<\fBQNewtonOpt\fP>: (

906

function = $..:mole

907

update<\fBBFGSUpdate\fP>: ()

908

convergence<MolEnergyConvergence>: (

909

cartesian = yes

910

energy = $..:..:mole

911

)

912

% give a partial guess hessian in internal coordinates

913

% the missing elements will be filled in automatically

914

hessian = [

915

[ 0.0109261670 ]

916

[ -0.0004214845 0.0102746106 ]

917

[ -0.0008600592 0.0030051330 0.0043149957 ]

918

[ 0.0 0.0 0.0 ]

919

[ 0.0 0.0 0.0 ]

920

[ 0.0 0.0 0.0 ]

921

[ 0.0 0.0 0.0 ]

922

]

923

)

924

)

925

926

.fi

927

.PP

928

.SS "Optimization with a Hydrogen Bond"

929

.PP

930

The automatic internal coordinate generator will fail if it cannot find enough redundant internal coordinates. In this case, the internal coordinate generator must be explicitly created in the input and given extra connectivity information, as is shown below.

931

.PP

932

.nf

933

934

% emacs should use -*- \fBKeyVal\fP -*- mode

935

% molecule specification

936

molecule<\fBMolecule\fP>: (

937

symmetry = C1

938

{ atoms geometry } = {

939

H [ 0.088 2.006 1.438 ]

940

O [ 0.123 3.193 0.000 ]

941

H [ 0.088 2.006 -1.438 ]

942

O [ 4.502 5.955 -0.000 ]

943

H [ 2.917 4.963 -0.000 ]

944

H [ 3.812 7.691 -0.000 ]

945

}

946

)

947

% basis set specification

948

basis<\fBGaussianBasisSet\fP>: (

949

name = 'STO-3G'

950

molecule = $:molecule

951

)

952

mpqc: (

953

checkpoint = no

954

savestate = no

955

% method for computing the molecule's energy

956

mole<\fBCLHF\fP>: (

957

molecule = $:molecule

958

basis = $:basis

959

coor = $..:coor

960

memory = 16000000

961

)

962

% molecular coordinates for optimization

963

coor<\fBSymmMolecularCoor\fP>: (

964

molecule = $:molecule

965

% give an internal coordinate generator that knows about the

966

% hydrogen bond between atoms 2 and 5

967

generator<\fBIntCoorGen\fP>: (

968

molecule = $:molecule

969

extra_bonds = [ 2 5 ]

970

)

971

)

972

% optimizer object for the molecular geometry

973

opt<\fBQNewtonOpt\fP>: (

974

function = $..:mole

975

update<\fBBFGSUpdate\fP>: ()

976

convergence<MolEnergyConvergence>: (

977

cartesian = yes

978

energy = $..:..:mole

979

)

980

)

981

)

982

983

.fi

984

.PP

985

.SS "Fixed Coordinate Optimization"

986

.PP

987

This example shows how to selectively fix internal coordinates in an optimization. Any number of linearly independent coordinates can be given. These coordinates must remain linearly independent throughout the optimization, a condition that might not hold since the coordinates can be nonlinear.

988

.PP

989

By default, the initial fixed coordinates' values are taken from the cartesian geometry given by the \fBMolecule\fP object; however, the molecule will be displaced to the internal coordinate values given with the fixed internal coordinates if have_fixed_values keyword is set to true, as shown in this example. In this case, the initial cartesian geometry should be reasonably close to the desired initial geometry and all of the variable coordinates will be frozen to their original values during the initial displacement.

990

.PP

991

.nf

992

993

% emacs should use -*- \fBKeyVal\fP -*- mode

994

% molecule specification

995

molecule<\fBMolecule\fP>: (

996

symmetry = CS

997

{ atoms geometry } = {

998

H [ 3.04 -0.69 -1.59 ]

999

H [ 3.04 -0.69 1.59 ]

1000

N [ 2.09 -0.48 -0.00 ]

1001

C [ -0.58 -0.15 0.00 ]

1002

H [ -1.17 1.82 0.00 ]

1003

H [ -1.41 -1.04 -1.64 ]

1004

H [ -1.41 -1.04 1.64 ]

1005

}

1006

)

1007

% basis set specification

1008

basis<\fBGaussianBasisSet\fP>: (

1009

name = '4-31G*'

1010

molecule = $:molecule

1011

)

1012

mpqc: (

1013

checkpoint = no

1014

savestate = no

1015

% molecular coordinates for optimization

1016

coor<\fBSymmMolecularCoor\fP>: (

1017

molecule = $:molecule

1018

generator<\fBIntCoorGen\fP>: (

1019

molecule = $:molecule

1020

)

1021

have_fixed_values = yes

1022

fixed<\fBSetIntCoor\fP>: [

1023

<OutSimpleCo>: ( value = -0.1

1024

label = 'N-inversion'

1025

atoms = [4 3 2 1] )

1026

]

1027

)

1028

% method for computing the molecule's energy

1029

mole<\fBCLHF\fP>: (

1030

molecule = $:molecule

1031

basis = $:basis

1032

coor = $..:coor

1033

memory = 16000000

1034

)

1035

% optimizer object for the molecular geometry

1036

opt<\fBQNewtonOpt\fP>: (

1037

max_iterations = 20

1038

function = $..:mole

1039

update<\fBBFGSUpdate\fP>: ()

1040

convergence<MolEnergyConvergence>: (

1041

cartesian = yes

1042

energy = $..:..:mole

1043

)

1044

)

1045

)

1046

1047

.fi

1048

.PP

1049

.SS "Transition State Optimization"

1050

.PP

1051

This example shows a transition state optimization of the N-inversion in using mode following. The initial geometry was obtained by doing a few fixed coordinate optimizations along the inversion coordinate.

1052

.PP

1053

.nf

1054

1055

% emacs should use -*- \fBKeyVal\fP -*- mode

1056

% molecule specification

1057

molecule<\fBMolecule\fP>: (

1058

symmetry = CS

1059

{ atoms geometry } = {

1060

H [ 3.045436 -0.697438 -1.596748 ]

1061

H [ 3.045436 -0.697438 1.596748 ]

1062

N [ 2.098157 -0.482779 -0.000000 ]

1063

C [ -0.582616 -0.151798 0.000000 ]

1064

H [ -1.171620 1.822306 0.000000 ]

1065

H [ -1.417337 -1.042238 -1.647529 ]

1066

H [ -1.417337 -1.042238 1.647529 ]

1067

}

1068

)

1069

% basis set specification

1070

basis<\fBGaussianBasisSet\fP>: (

1071

name = '4-31G*'

1072

molecule = $:molecule

1073

)

1074

mpqc: (

1075

checkpoint = no

1076

savestate = no

1077

% molecular coordinates for optimization

1078

coor<\fBSymmMolecularCoor\fP>: (

1079

molecule = $:molecule

1080

generator<\fBIntCoorGen\fP>: (

1081

molecule = $:molecule

1082

)

1083

followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ]

1084

)

1085

% method for computing the molecule's energy

1086

mole<\fBCLHF\fP>: (

1087

molecule = $:molecule

1088

basis = $:basis

1089

coor = $..:coor

1090

memory = 16000000

1091

)

1092

% optimizer object for the molecular geometry

1093

opt<\fBEFCOpt\fP>: (

1094

transition_state = yes

1095

mode_following = yes

1096

max_iterations = 20

1097

function = $..:mole

1098

update<\fBPowellUpdate\fP>: ()

1099

convergence<MolEnergyConvergence>: (

1100

cartesian = yes

1101

energy = $..:..:mole

1102

)

1103

)

1104

)

1105

1106

.fi

1107

.PP

1108

.SS "Transition State Optimization with a Computed Guess Hessian"

1109

.PP

1110

This example shows a transition state optimization of the N-inversion in using mode following. The initial geometry was obtained by doing a few fixed coordinate optimizations along the inversion coordinate. An approximate guess Hessian will be computed, which makes the optimiziation converge much faster in this case.

1111

.PP

1112

.nf

1113

1114

% emacs should use -*- \fBKeyVal\fP -*- mode

1115

% molecule specification

1116

molecule<\fBMolecule\fP>: (

1117

symmetry = CS

1118

{ atoms geometry } = {

1119

H [ 3.045436 -0.697438 -1.596748 ]

1120

H [ 3.045436 -0.697438 1.596748 ]

1121

N [ 2.098157 -0.482779 -0.000000 ]

1122

C [ -0.582616 -0.151798 0.000000 ]

1123

H [ -1.171620 1.822306 0.000000 ]

1124

H [ -1.417337 -1.042238 -1.647529 ]

1125

H [ -1.417337 -1.042238 1.647529 ]

1126

}

1127

)

1128

% basis set specification

1129

basis<\fBGaussianBasisSet\fP>: (

1130

name = '4-31G*'

1131

molecule = $:molecule

1132

)

1133

mpqc: (

1134

checkpoint = no

1135

savestate = no

1136

% molecular coordinates for optimization

1137

coor<\fBSymmMolecularCoor\fP>: (

1138

molecule = $:molecule

1139

generator<\fBIntCoorGen\fP>: (

1140

molecule = $:molecule

1141

)

1142

followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ]

1143

)

1144

% method for computing the molecule's energy

1145

mole<\fBCLHF\fP>: (

1146

molecule = $:molecule

1147

basis = $:basis

1148

coor = $..:coor

1149

memory = 16000000

1150

guess_hessian<\fBFinDispMolecularHessian\fP>: (

1151

molecule = $:molecule

1152

only_totally_symmetric = yes

1153

eliminate_cubic_terms = no

1154

checkpoint = no

1155

energy<\fBCLHF\fP>: (

1156

molecule = $:molecule

1157

memory = 16000000

1158

basis<\fBGaussianBasisSet\fP>: (

1159

name = '3-21G'

1160

molecule = $:molecule

1161

)

1162

)

1163

)

1164

)

1165

% optimizer object for the molecular geometry

1166

opt<\fBEFCOpt\fP>: (

1167

transition_state = yes

1168

mode_following = yes

1169

max_iterations = 20

1170

function = $..:mole

1171

update<\fBPowellUpdate\fP>: ()

1172

convergence<MolEnergyConvergence>: (

1173

cartesian = yes

1174

energy = $..:..:mole

1175

)

1176

)

1177

)

1178

1179

.fi

1180

.PP