The NCFG configuration format

The behaviour of the NOMAD VR routines is controlled by a ncfg file which tells the program what datasets to load, what timesteps to show, and multiple other options to optimize the visualization experience.

This is a text-based list of options. The options are explained below, with a set of example usecases. A full list of options can also be read.

A collection of tutorials serves as an introduction to the most commonly used parameters.

Tutorial 1: Preparation of atomic structure and electron density dataset (from gaussian cube)

Tutorial 2: Preparation of Fermi surface

Tutorial 3: Preparation of atomic structure and electron density dataset (from collection of gaussian cubes, using scripting to automate the procedure)

Tutorial 4: Preparation of atomic structure or molecular dynamics (from xyz)

Tutorial 5: Visualizing simulations from Archive and Analytics (See also Tutorial 10 if you use Google Cardboard)

Tutorial 6: Visualizing crystal structures from the encyclopedia

Tutorial 8: In-Silico Skin Model – A molecular model for the top layer (Stratum Corneum) of human skin

Examples using NOMAD VR in other domains:

Tutorial 7: Preparing HDF5 datasets. Example using climate data from the ClimEx Project.

Other examples:

Step by Step 1: Creating stereoscopic videos using NOMAD VR on HTC Vive / Oculus Rift

You can download the NOMAD VR User Manual (including the tutorials) from here.

General considerations

Colours are indicated as RGB (opaque) or RGBA (transparent), with values ranging from 0 to 1.

Positions are indicated in Ångstrom.


White background:

background 1 1 1

Path for files mentioned in the config file

path "data\"

Initial user position

Use userpos to specify the starting position of the user. Example to position the user at the origin:

userpos 0 0 0


The speed of the user and of the timesteps can be changed by the options animationspeed and movementspeed

animationspeed 0.5

movementspeed 2

shows the animation at half the normal speed and the user movement at twice the normal speed.

Crystal Structures from the encyclopedia

(See also tutorial 6)

To change the atom size we have an scaling value, with initial value of 1.

atomscaling 0.5

The encyclopedia produces two JSON files with the crystal structure. In our example, 131424_cells.json and 131424_elements.json

encyclopediajson "131424"

Crystal Structures, molecular dynamics or geometry optimization from the archive and analytics

(See also tutorial 5)

The archive provides one JSON file with the calculation information.

analyticsjson "material.json"

General crystal structures

The unit vectors are indicated as

abc 20.022 0.0 0.0 0.0 19.899 0.0 0.0 0.0 13.383

The nine values correspond to the vectors, in order

The unit cell can be displayed explicitly


or repeated

repetitions 2 3 1

The atoms may be loaded from an xyz file:

xyzfile ""

or from a cube file (volumetric data in cube files is currently ignored)

cubefile "111_t1_4830.cube"

If the system is non-periodic, you may indicate it as


otherwise, atoms near unit cell boundaries will be repeated if you show one unit cell

Atomic bonds can be shown with the option


Bonds are shown if the distance between atoms is smaller than the sum of their covalent radii. This can be adjusted with the bondscaling parameter (useful for gas phase, for example).

By default a bondscaling of 0.5 is used.


The RGB colour of some elements can be changed (r g b below are numbers between 0, dark, and 1, bright):

bondscolour r g b

atomtrajectorycolour r g b

unitcellcolour r g b

supercellcolour r g b

Atom display

The colour of an atom type can be changed with the atomcolour option. New atoms can be created with the newatom option (r g b below are numbers between 0, dark, and 1, bright):

atomcolour He 1 0 0

newatom TX r g b 1.0

makes helium atoms red and creates a new particle type TX, with RGB colour, and a radius of 1.0 angstrom. Use these options before the option xyzfile if these new atom types are included in the XYZ file.

Molecular dynamics without electron density

Molecular dynamics simulations are often included in xyz files by concatenating the timesteps.

xyzfile ""

The number of timesteps to load can be indicated explicitly

timesteps 30

The trajectories of a list of atoms may be shown (in red)

showtrajectory 3 5

shows the trajectory of the third and fifth atom in the atom file.

showtrajectory -1

shows the trajectory of all atoms

Molecular dynamics with electron density

Collections of cube files can be preprocessed (see tutorials 1 and 3 for details) into a list of isosurfaces, which can then be visualized in VR. The relevant options are timesteps, isos, values, colours and translations. Example

timesteps 3

isos 2

values "a" "b"

colours 1 0 0 0.5          -1 -1 -1 -1

translations 0 0 0       5 5 0

This example would load the two isosurfaces for each of 3 timesteps, from files 1-a.ply, 1-b.ply, ..., 3-a.ply, 3-b.ply. Isosurface a would be shown red, semitransparent, while isosurface b would use the colours from the ply file. Isosurface a would not be displaced, while isosurface b would be displaced by the vector (5 5 0).


Multiple electron density simulations for different hole positions can be shown by using the options described in the previous section.

In addition, you may specify atom positions once and reuse them by the option



Markers can be used to indicate positions in the system. Typically, hole positions are shown in exciton visualizations.

The markers consist of a six-pointed, three-dimensional star shape. One marker per timestep is specified by its coordinates using the markers keyword. The colour can be also adjusted using markerscolours.

markers 0 0 0        1 0 0

markercolours 1 0 0 1         0 1 0 1

markerscaling 0.8

This example for a two-timestep file generates one red, opaque marker at the origin for timestep 1 and a green, opaque marker at position (1 0 0) for timestep 2. The markers have the default size.

If no marker colours are specified, a default colour will be used. The default colour is chosen so that it can be distinguished from the background.

Information Boxes

If you want to provide additional information about a given atom you can add an info box at a given position and size, with a line pointing to a given atom. The box sides will display a selected image. Example:

info 20 10 30 2 15 "file.png"
infolinecolour 1 0 0

Put an info box at 20 10 30 with scaling 2, and put a line from the box to atom 15. Use file.png for the sides.
Make the line colour red (1 0 0).

The line colour is global for all infoboxes.
The line will follow the atom as the atom moves.

Options for HTC Vive (ignored in other platforms without the suitable capabilities)

If you want the controllers to vibrate when you touch an atom


Normally, you want to see your controllers and base stations in VR. But for video recording, they may be distracting, so in this case you don't want them shown.
If you want to show the controllers and base stations


The menu button on controller 2 starts and stops the recording of screenshots. The base name of the screenshot is set by

screenshot "C:\temp\frame"

in order to have the files frameL0000.bmp, frameL0001.bmp, etc saved to C:\temp.

Stereo screenshots are enabled by the option stereoscreenshot.

The user can fly through the scene by pointing and pressing the trigger. If you prefer gaze-based navigation, use the following option:


The second controller's menu button can be used to create screenshots or to show/hide information boxes. It can also be disabled. The option is menubutton and the parameter is either Record, Infobox or Nothing, respectively.


menubutton Nothing

The default option is Record.

The bondthickness is used to make the bond line thicker

bondthickness 2

The sidebuttontimestep selects the behaviour of the side button to control the timestep: +1: next timestep; -1: previous timestep; 0: do nothing.

sidebuttontimestep +1

Options for Google Cardboard / GearVR (ignored in other platforms)

The glyph used to display atoms can be chosen between icosahedron (default), octahedron or tetrahedron. Example

atomglyph octahedron

Additionally, a UV sphere (tesselated sphere with longitude and latitude lines) is created by the word sphere followed by the subdivision level.

atomglyph sphere 10

The bondthickness is used to make the bond line thicker

bondthickness 2