In this tutorial you optimise the geometry of a water molecule with NWChem at the Hartree-Fock level, then look at the energy, the optimisation steps and, optionally, the vibrational frequencies.
You need:
- ECCE installed and started with
ecce(see Installation). - NWChem installed, so that the command
nwchemworks in a terminal. The machinelocalhostruns it for you (see Machines).
The calculation takes seconds.
A project is a folder that holds calculations. Every calculation belongs to a project.
- In the Organizer, select your home folder in the tree on the left.
- Choose File > New > Project.... You can also right-click the folder and choose New... > Project....
- In the window "New Project Name", enter
tutorial. - Click OK.
The project appears in the tree. Names may contain letters, digits, .,
_ and -.
- Select the project
tutorial. - Choose File > New > NWChem Calculation.... You can also right-click the project and choose New... > NWChem Calculation....
- In the window "New Calculation Name", enter
water-opt. - Click OK.
The calculation appears under the project, with the run state Created. It has no molecule yet.
By default ECCE does not open an editor for the new calculation. (The Organizer menu Options has the entry Invoke Default Tool at Creation if you prefer that.)
- Select
water-opt. - Click Builder below the calculation's details in the Organizer.
The Builder opens on this calculation. (If you have not used the Builder before, Importing a structure shows how to open existing structure files in it.) To add water from the structure library:
- In the Mode Toolbar, click the button with the tooltip Import from Structure Library. You can also choose Mode > Add Structure (Ctrl+7).
- In the Structure Library panel, choose
Inorganicin the Libraries drop-down, then open the folderSmall_inorganic_moleculesby double-clicking it. The button next to the drop-down goes up one level. - Click
Waterin the list. A preview appears in the panel. - Click in the empty 3D view. The molecule is added there.
If you prefer to draw the molecule yourself:
- An empty structure opens ready to place carbon, the element shown on the round chip in the Mode Toolbar. Otherwise choose Mode > Atom (Ctrl+5), or click that chip.
- Choose the element O: click Element selector, the small periodic table beside the chip, and pick O in the table that opens below it.
- Click in the empty 3D view to place the oxygen atom.
- Choose Build > Add Hydrogen (Ctrl+F) to complete the valence with hydrogen atoms.
- Choose Build > Clean (Ctrl+K) to tidy the geometry.
The default shape of oxygen is Bent, with two open bonds, and Add Hydrogen fills each open bond with a hydrogen atom.
To join two atoms yourself, click the Bond button in the Mode Toolbar (two grey balls joined by a stick; tooltip Draw bonds), or choose Mode > Bond (Ctrl+6). Click the first atom, then hold Shift and click the second. The kind of bond (Covalent or Metal-π) is chosen in the Build panel, not on the button. The button stays pressed while Bond mode is active; press Esc or click another mode button to leave it.
Then save the structure:
- Choose File > Save (Ctrl+S).
- Close the Builder with File > Quit (Ctrl+Q). If it asks "Save Builder Changes?", save.
- Select
water-optin the Organizer. - Click Editor.
The editor shows what you built under Chemical System: Formula:
H2O, Atoms: 3, Electrons: 10. Charge: is 0 and Spin
Mult.: is Singlet, which is correct for water.
Set the rest:
- Under Code, check that the button shows NWChem.
- In the NWChem Settings box, choose
RHFin Theory:.RHFis restricted Hartree-Fock for a closed-shell molecule. - In Runtype:, choose
Geometry. This optimises the geometry. - Under Basis Set, click Quick Basis Menu, then choose
6-31G*. The fields Name:, Polarization:, Functions: and Primitives: show the chosen basis set. - Click Verify. This checks the input for obvious problems before you submit it.
- Choose File > Save (Ctrl+S).
The buttons Theory Details... and Runtype Details... open further options for the chosen theory and run type. The defaults are right for this calculation.
Generated input keeps multiword titles, including names such as
Water, B3LYP-D3(BJ)/def2-SVP, minimum. ECCE-QM writes the structure title
on its title line; ORCA carries it in a comment, replacing any # in the title
with a space. NWChem uses the calculation
annotation for its displayed title. CP2K project names and Quantum ESPRESSO
prefixes remain identifiers with their existing character and length limits.
To see the input file ECCE will send to NWChem, click Final Edit....
The button is enabled when the setup is complete (the run state is
Ready). It opens the input file in your text editor: the editor set in
Edit > Preferences, otherwise the one named by the VISUAL or EDITOR
variable. If you close the editor without saving, nothing changes. If you
save a change, ECCE uses your edited file, and later changes in the
Electronic Structure Editor ask before they replace it.
ECCE remembers the input file it generated. If you have changed that file by hand, or replaced it with one of your own, Save asks before it generates a new one: Keep my input saves the settings and leaves the file as it is, Regenerate replaces it with a file built from the settings (your edits are lost), and Cancel saves nothing.
- In the editor, click Launch.... Or select the calculation in the Organizer and choose Tools > Launcher... (Ctrl+L).
- In the Launcher, choose
localhostin Machine:. - Run Directory: starts as
ecce-runsin your home folder (for example/home/<you>/ecce-runs) when no directory is saved for this machine. Change it if you want the job to run elsewhere. The path must start with/or~. ECCE creates the folder, with its parents, if it does not exist. - Click Launch.
The Launcher shows progress messages and, at the end, "Successfully submitted job."
For localhost the Launcher shows Processors:, Priority: and Run
Directory:. There are no login, password or remote shell fields: the job
runs as you, on this computer. Scratch Directory:, Username: and
Machine settings... are under Advanced, which is closed until you
click it. Queue:, Nodes:, Alloc. Account:, Wall Time Limit:,
Scratch Space: and Memory Limit: belong to machines that run jobs
through a batch queue, and appear for those machines. A machine reached
over the network shows the Remote Machine Access fields (Username:,
Password:, Remote Shell:).
On a batch-queue machine, Processors: is the total number of cores.
Threads per rank: (default 1) splits them between MPI ranks and OpenMP
threads: the number of ranks is Processors divided by Threads per
rank, and the Launcher shows it as MPI ranks: N (M per node). If
Processors is not a multiple of the threads, or the ranks do not divide
evenly over the nodes, a warning appears in the Launcher's notes; the job
can still be launched. With more than one thread the job script requests
--ntasks-per-node and --cpus-per-task from Slurm and sets
OMP_NUM_THREADS, and a CP2K job runs the OpenMP binary cp2k.psmp in
place of cp2k.popt. The value is saved with the calculation.
Under Threads per rank the Launcher shows Books N core-h (cores x wall time), the cores times the Wall Time Limit, and updates it as you change either. Queues that book whole nodes are not known to the machine entry, so the figure counts the cores as you set them. The calculation summary then shows Booked (the same figure) and, once the job has run, Used: the cores times the time the job ran.
Memory Limit: is entered in GB for every code and is a request per node;
the Launcher converts it to the unit the scheduler wants when it writes the
job script (for Slurm, --mem). When the queue has a memory limit, the
Launcher shows it beside the field as the memory of a node. Leave the field
at 0 to request none.
Return to the Organizer. The icon of water-opt shows its run state.
Options > Show Run State Legend (on by default) lists the states and
their icons.
The states you see, in order, are Submitted, Running and Complete. A calculation that ended with an error is Failed or Unsuccessful. An ORCA optimisation that stopped at its cycle limit, and a CP2K run whose SCF or optimisation did not converge, are Unsuccessful too: the code ended normally, but its energy or structure is not a result. The summary gives the reason; the outputs are kept. You can also select the calculation and read its summary in the panel next to the tree.
While a job is Submitted, waiting in a batch queue, the summary has a Progress box that says since when it has been queued and, if the machine gave one, the job id. It does not show the queue's own state for the job; to see that, choose Check Job on Machine from the Run Mgmt menu. If ECCE loses contact with the job's monitor, the box turns grey and says when the job was last heard from.
To read the files while the job runs, select the calculation and use the Run Mgmt menu:
- Tail -f on Output File... follows the output as it grows, in a window of its own over the login ECCE already has for the machine, so it does not ask for the password again. Pause holds the view while new lines keep arriving; Resume shows them.
- View Output File... and View Input file... open the files.
- View Run Log... shows ECCE's log of the job.
If the state is Failed, open View Output File... and read the end
of the file. The most common causes are a wrong path to the code (see
Machines) and an input error that Verify would have
reported. On a machine with a queue system (Slurm, PBS, SGE) the code's
own error can be in the queue's error file instead, such as slurm.err.
ECCE brings that file back into the calculation's Outputs when it has
text in it, and the reason shown for a failed calculation names it.
Use the vertical mouse wheel or two-finger vertical scrolling to zoom the molecule. Horizontal scrolling leaves the zoom unchanged. Pinch two fingers apart to zoom in, or together to zoom out, on systems that provide pinch gestures. Scroll movement is combined for each frame to keep zoom responsive.
Click the 3-D view to give it keyboard focus, then press + or − to zoom in or out; the keypad + and − work too. Keys typed in text fields continue to edit the text.
- Select
water-opt. - Click Viewer.
The Viewer shows the final geometry. (The same Viewer shows the output of a calculation run elsewhere: see Importing a calculation.) Open the results from its Properties menu. Each entry shows or hides a panel. A panel whose plot or table needs more room can be dragged out by its title bar into a window of its own; Tools > Dock Floating Panels puts them back. See Arranging the Viewer's panels.
- Calculation Summary lists the theory, run type and basis set, and when and where the job ran.
- Energies lists the energies of the calculation, including Total Energy. For an NWChem RHF geometry run the rows are Nuclear Repulsion Energy, One-Electron Energy, Total Energy and Two-Electron Energy, each in Hartree.
- Geometry Trace plots one quantity against the geometry step, one point for each step. It opens on the Energy Gradient Magnitude. To plot the energy, right-click the panel and choose Total Energy; the picture below shows that plot. The energy is drawn relative to step 1 in kJ/mol, and the title gives the final absolute energy in Hartree. Click a point on the plot to see the molecule at that step, or use the playback control to step through them; Play continues from the selected step. (A calculation with a Geometry Trace has no separate Geometry Step Plots entry: the trace's right-click menu plots the same per-step quantities.) Delay: sets the time between steps during playback (milliseconds); tick Loop to play forward to the last step and back, until stopped. All plots zoom with the mouse wheel (Shift+wheel zooms the vertical axis only) or by dragging a rectangle, but never beyond the data; Home or a double click on empty plot shows all of it. In the Wave Step Plots (the SCF cycles), the energy change and the density and orbital gradient changes are drawn as log10 of their size.
For a converged optimisation the energy decreases from step to step and levels off in the last steps, and the gradient falls towards zero.
To also compute vibrational frequencies, repeat the tutorial with a second calculation:
- In the project, select
water-optand choose Edit > New from This > Duplicate. Or create a new calculation as in step 2. - In the Electronic Structure Editor, choose
GeoVibin Runtype:.GeoViboptimises the geometry and then computes the frequencies. Edit > New from This > Duplicate copies the calculation with its structure and settings and resets it, ready to launch. - Save and launch as before.
- In the Viewer, choose Properties > Vibrational Frequencies.
- Use the Table and Graph tabs to see the three frequencies.
- Choose Animation and select a frequency to see the motion. Amplitude: sets the size of the displacement and Delay: the speed. Vector shows arrows and stops the animation.
A geometry optimisation that has reached a minimum has no imaginary frequencies.
ORCA, Gaussian 16, NWChem, ECCE-QM, MOPAC, CP2K and Quantum ESPRESSO calculations can keep final orbitals or density for a follow-on calculation's initial guess.
- Select the finished calculation and choose New from This > Continue from Final Orbitals in the Organizer. The copy starts from the last geometry and its orbitals. The item is grey when no orbital file was stored. Gaussian 16 needs Create Checkpoint File enabled in the source, or a stored results.h5 with orbitals (see below).
- Open the copy in the Calculation Editor. Under Settings, Initial guess: MOs from names the source. Save to generate the input that reads the guess.
- ORCA and Gaussian 16 can project onto another basis; the line says (projected from the old basis**)**. NWChem and ECCE-QM need the same basis set. CP2K needs the same basis settings in Theory Details, including any per-element overrides, and the same atoms in the same order. MOPAC needs the same atoms in the same order; its Hamiltonian may change. Quantum ESPRESSO reuses the charge density, with the same atoms at the same positions, cell and wavefunction and charge-density cutoff settings. The editor reports incompatible structure or basis settings on the guess line.
- Use Default Guess drops the attached file and restores the program's default guess.
The binary guess file is copied to the run machine for local and remote
jobs. Use it with the same program version and a compatible machine.
MOPAC reads the staged density with OLDENS; CP2K reads the staged
wavefunction with SCF_GUESS RESTART.
When a Gaussian 16 calculation has no stored checkpoint (it was deleted, or
the Preferences switch below discarded it) but has a results.h5 with
orbitals, Continue from Final Orbitals writes those orbitals into the
copy's input and Gaussian reads them with Guess=Cards. The guess line in
the Calculation Editor ends with from its results.h5 (or from its
checkpoint when the checkpoint is used; it is preferred when both exist).
Orbitals read this way are not projected: the copy needs the same basis set
and the same atoms in the same order, and the line says so when they differ.
Edit > Preferences, tab Data, Discard the programs' own binary files once results.h5 is written is off by default. When it is on, a Gaussian 16 job that finishes afterwards keeps no checkpoint once its results.h5 has passed its checks; the text outputs are always kept.
The copy reads the source's converged charge density with startingpot='file'.
Wavefunctions are generated afresh: storing just the density and its metadata
keeps transfers small, including when the source did not keep wavefunctions.
Use the same pseudopotentials and spin settings as the source. If you change
atoms, cell or cutoff settings, restore them or choose Use Default Guess.
In Theory Details... of an ORCA DFT calculation, Grid: sets the
numerical integration grid. Default leaves ORCA's own choice. DefGrid1,
DefGrid2 and DefGrid3 write DEFGRID1, DEFGRID2 or DEFGRID3 in the
! line; each step is a finer grid and a slower calculation. ORCA's DefGrid
setting applies to the DFT grid and, with Use RIJCOSX, to the exchange grid
as well. Use a finer grid when the result seems to depend on how the molecule
is oriented, or for functionals such as the meta-GGAs that are sensitive to
the grid.
For a mixture of solvents, or any solvent the list does not name, tick Use
implicit solvation (ORCA) or Use SCRF (Gaussian 16) in Theory
Details... and choose Custom as the solvent. Two fields become available:
Dielectric constant (the static value, epsilon) and Refractive index (n;
the optical dielectric constant used is n squared). In ORCA, Custom works with
the CPCM model only; SMD needs solvent parameters that ORCA keeps for its named
solvents. The Calculation Summary shows such a solvent as Custom (ε = 30.0, n = 1.42).
In Runtype Details... of an ORCA Geometry or GeoVib calculation:
- Find: Minimum is ORCA's ordinary optimisation. Transition State
writes
! OptTSand searches for a saddle point. A transition-state search needs a good initial Hessian, so set Initial Hessian to Calculate (or to Read from previous calculation). With neither, the input checker warns; the calculation is not blocked. - Initial Hessian: Default keeps ORCA's model Hessian. Calculate
writes
Calc_Hess true. Read from previous calculation writesinhess readand the name of the Hessian file (.hess) of the calculation this one was made from with Edit > Duplicate with Final Orbitals. That file exists only if the earlier job computed a Hessian (a frequency job, or an optimisation with Calculate). If none is attached the checker warns and ORCA uses its default.
A molecule of a single atom has no geometry to optimise, and ORCA stops
without an energy if asked to. ECCE therefore writes the input without Opt:
a Geometry run is a single point, and a GeoVib run keeps Freq, so
the energy and the thermochemistry are still computed.
NWChem's plane-wave module, NWPW, has no code of its own in the list of codes. Choose it in the Theory: list of an NWChem calculation: PSPW or BAND. Neither needs a basis set. Car-Parrinello molecular dynamics is a run type of PSPW; choose it in Runtype: after you have chosen PSPW.
Change the theory to RDFT, or the basis set to cc-pVTZ, and compare the
total energy. The next chapters describe each window in more detail.




