Electrostatic Potential Maps

An electrostatic potential map colours a molecule’s surface by the potential a positive test charge would feel there: red where the molecule is electron-rich, blue where it is electron-poor. Molkit shows maps in the 3D viewer. Import a map from cube files, or calculate one from the drawing through a helper program on your own computer. Maps are saved in the .mkit file, exported with the SVG, and shown by the structure widget.

The map buttons

The 3D viewer has two map buttons next to its view toggles.

Electrostatic potential map shows or hides the map. When the molecule has no map yet, it opens the options instead.
Map options opens the options panel. Esc closes the panel without closing the viewer.

A map belongs to one molecule, so with several molecules in the scene there is no map to show.

While the map is on, a legend shows the colour scale with its low, middle and high values.

Calculating a map

A calculation needs the calculation helper running on your computer (see The calculation helper). When the options panel finds it, it shows these fields:

Field	What it does
Charge	The net charge, read from the formal charges in the drawing. Change it if the drawing is not what you want calculated
Unpaired e⁻	The number of unpaired electrons, read from the drawn radical dots. An odd electron count gets one unpaired electron, and O2 is calculated as a triplet; a note says so
Method	The level of theory. The first choice, B3LYP/def2-SVP (OCC), is the default. HF/3-21G (OCC) and GFN2-xTB (xTB) are also offered when those programs are found
Relax the geometry first	On by default. xTB relaxes the built geometry before the potential is computed. Charged species and zwitterions are relaxed in a water model, shown as “(in water)”. Shown only when xTB is found

Click Calculate (or Recalculate). The panel shows the current stage and a Cancel button. The potential itself is always calculated in the gas phase. If relaxing would change which atoms are bonded, the map is computed on the built geometry instead, with a note.

If you select another molecule meanwhile, the map is still stored for the one it was started for.

Using the map’s geometry

A relaxed map sits on a slightly different geometry from the one Molkit built. While such a map is shown, the model moves to the map’s geometry and the viewer’s label reads “Geometry of the map”. Use this geometry for the molecule makes that geometry the molecule’s 3D structure everywhere: the 3D view, the dipole and exports then use it, and it is saved with the document. Back to the built geometry undoes this.

Importing cube files

Click Import cube files… and pick the potential file, and the electron density file from the same calculation if you have it (.cube or .cub, one or two files). Without a density file, the surface is built from free-atom densities.

The cube file’s atoms must be in Molkit’s order. Save coordinates downloads molecule.xyz with the geometry on screen, its charge and its unpaired electrons, to run the outside calculation on. A map on a slightly different geometry is shown on its own geometry; one for a different shape is refused.

Remove map deletes the map from the molecule.

Display options

Once a molecule has a map, the options panel also offers:

Option	Choices	Default
Opacity	0.2 to 1	0.8
Colours	Rainbow (textbook); Red, green, blue; Red, white, blue; Orange, white, violet (colour-blind safe)	Rainbow (textbook)
Range	This molecule (fitted to the map), or Fixed with a ± value	This molecule; Fixed starts at ±150 kJ/mol
Unit	kJ/mol, kcal/mol, a.u. (atomic units)	kJ/mol
Surface	Tight (0.004), Standard (0.002), Loose (0.001), the electron density of the surface in e/bohr³	Standard (0.002)
Show	Surface; A cut through the molecule; Surface and cut	Surface

Red is always the negative end. The options are remembered in your browser, apply to every map, and need no new calculation.

The cut

With a cut shown, three more controls appear. Cut picks the plane: The molecule’s own plane, Across it, lengthwise, or Across it, crosswise. Position moves the cut up to 3 Å either way along its normal. Contour lines draws lines of equal potential on the cut. Choosing a cut turns the view to face it.

Out-of-date maps

After any edit to the molecule (an atom, a bond order, a charge), its map is out of date: the map button is marked, and the old map is not drawn or exported. Undoing the change brings it back. Discard it in the options removes the old map; a new map replaces it.

Saving, capturing and exporting

Saving. Maps are saved in the .mkit file, with any geometry you adopted. Only the maps of molecules in that document are written. See .mkit Files.
Capturing. A PNG capture from the viewer includes the map when it is on.
Pop-out window. The pop-out 3D window has its own map button and legend, and uses the options chosen in the panel.
SVG export. The Export SVG dialog’s Electrostatic maps option writes the map Inside the SVG (one file), as a Separate file (on demand) with the .esp extension in a folder you name (esp by default), or leaves it out. The SVG records the method, the geometry it was calculated on, the surface, a citation and a caption, along with your display options and, when the map is on in the viewer at export time, the camera angle. See SVG Export and Chemistry metadata.

The calculation helper

Calculations go through a small helper program that is part of the Molkit folder and needs Node.js. Start it from the Molkit folder:

npm run calc-helper

The helper lists the programs it found and listens on http://127.0.0.1:47821/. Leave its window open while you calculate; Ctrl+C stops it. An open options panel looks for the helper every few seconds.

OCC computes the B3LYP/def2-SVP and HF/3-21G potentials. It is found among the Molkit folder’s installed packages (@peterspackman/occjs).
xTB relaxes geometries and offers the GFN2-xTB potential. It is a separate program. The helper looks for xtb at the path in the MOLKIT_XTB environment variable, then on your PATH, then in %LOCALAPPDATA%\Programs\xtb, ~/xtb and ~/.local/xtb. Without xTB there is no relax option.

The helper accepts requests only from your own computer, and only from pages on molkit.com. Chrome may ask once whether molkit.com may reach programs on your device; if you refuse, Molkit finds no helper. --allow-origin followed by a site’s address lets another site ask. The helper runs one calculation at a time, for molecules of up to 200 atoms.

Molkit’s development server (npm run dev, opened as localhost) answers calculation requests itself, without the helper.

With no helper running, the options panel reads “No calculation helper is running on this computer (start it with “npm run calc-helper” in the Molkit folder); a map can still be imported from cube files.”