User Manual

Version 1.1.0

Developed by:
Jasmin B. Maglic, Roy Lavendomme

Download program and source code at

https://molovol.com
https://github.com/molovol/MoloVol

Contact:
molovol@outlook.com

2022-10-11
Table of Contents
1. General information ........................................................................................................................ 2
1.1. What is MoloVol ...................................................................................................................... 2
1.2. How to cite .............................................................................................................................. 2
1.3. How does the program perform calculations ......................................................................... 2
1.4. Contact the development team .............................................................................................. 2
1.4.1. Bug report........................................................................................................................ 2
1.4.2. Feature request ............................................................................................................... 2
2. How to use MoloVol ........................................................................................................................ 3
2.1. What can be calculated with MoloVol .................................................................................... 3
2.1.1. Single-probe mode .......................................................................................................... 4
2.1.2. Two-probe mode ............................................................................................................. 5
2.1.3. Example of calculation result .......................................................................................... 6
2.2. Graphic user interface ............................................................................................................. 7
2.3. Command line interface .......................................................................................................... 8
2.4. Web app ................................................................................................................................ 11
2.5. Parameters and options ........................................................................................................ 11
2.5.1. Include HETATM ............................................................................................................ 11
2.5.2. Analyze crystal unit cell ................................................................................................. 11
2.5.3. Calculate surface area ................................................................................................... 11
2.5.4. Enable two-probe mode ................................................................................................ 12
2.5.5. Small probe radius ......................................................................................................... 12
2.5.6. Large probe radius ......................................................................................................... 12
2.5.7. Grid resolution............................................................................................................... 13
2.5.8. Optimization depth ....................................................................................................... 13
2.6. Input files ............................................................................................................................... 13
2.6.1. Chemical structure ........................................................................................................ 13
2.6.2. Element properties ........................................................................................................ 14
2.6.3. Crystallographic space groups ....................................................................................... 14
2.7. Exporting and reading results................................................................................................ 14
2.7.1. Manual exportation ....................................................................................................... 14
2.7.2. Automatic exportation .................................................................................................. 15
2.7.3. Visualizing isosurfaces ................................................................................................... 15
3. Calculation examples and results analysis .................................................................................... 20
3.1. Open cage with wide gaps..................................................................................................... 20
3.2. Deep cavitand ........................................................................................................................ 20
3.3. Open macrocycle ................................................................................................................... 21
3.4. Giant open cage..................................................................................................................... 21
3.5. Crystalline porous material ................................................................................................... 22

1
 1. General information
1.1. What is MoloVol

MoloVol is a program intended for chemists and chemistry related users. The program can provide
volumetric and surface data from chemical structures.

MoloVol is designed to be user friendly with a simple user interface, accessible on most common op-
erating systems for computers (i.e., Windows, macOS and Linux) and highly parametrizable.

MoloVol is coded in C++, freely distributed and open source under the MIT license.

1.2. How to cite

MoloVol v1.0.0 features and algorithms are presented in detail in an open access scientific article pub-
lished in the Journal of Applied Crystallography. ( https://doi.org/10.1107/S1600576722004988 ).

MoloVol results should be reported with a reference to this article. The list of parameters given in the
calculation report should be included in the methods or experimental section. Please also include the
application version to ensure reproducibility, as there may be slight differences between versions.

Reference:
J. B. Maglic, R. Lavendomme. MoloVol: an easy-to-use program for analyzing cavities, volumes and
surface areas of chemical structures. J. Appl. Cryst. 2022, 55, 1033–1044. DOI:
10.1107/S1600576722004988

1.3. How does the program perform calculations

It is sometimes useful to understand how a program works to make best use of its functions. A com-
prehensive overview of version 1.0.0 is provided in the scientific publication (see 1.2). Details about
the code and functions of following versions will be added to the wiki of the GitHub repository page
(work in progress): https://github.com/molovol/MoloVol/wiki

1.4. Contact the development team

Bug reports and feature requests can be sent via e-mail ( molovol@outlook.com ) or in the “issues”
section of the program repository ( https://github.com/molovol/MoloVol/issues ).

1.4.1. Bug report

If you encounter a bug while running the program, please report to the development team with a
description of the bug, the suspected cause of the bug, the operating system and specify how to re-
produce it.

1.4.2. Feature request

MoloVol was developed to include features meant to be useful for chemists desiring to calculate vol-
umes and surface areas of chemical structures that are not easily obtainable from other programs. If
you consider that an additional feature could benefit the chemistry community, you can suggest it by
explaining why it would be useful and giving more details about scientific aspects the development
team need to be careful about. The feature requests will be considered and potentially added in future
version of MoloVol if it can fit in the code and we have time to program the feature.

2
You can find below a list of features already considered for future versions:

- Add the ability to list connected cavities. Some cavities might be “separated” but partially
overlapping (probes can touch but not travel from one cavity to the other). Listing such con-
nections could help users identifying cavities and their locations.
- Add automatic identification of continuous pores in crystals during the crystal unit cell anal-
ysis.
- Implement parallel programming. While MoloVol program performs decently fast, it may be
possible to further accelerate calculations by using multiple CPU or GPU cores in parallel. This
feature is considered but may not be implemented unless there is a high demand for improved
performance.
- Display atoms and surfaces within MoloVol. Currently MoloVol offers the possibility to export
surface maps to be visualized in third-party programs such as PyMOL and Chimera. It could
also be possible to directly display the chemical structure and surfaces within MoloVol.

2. How to use MoloVol

2.1. What can be calculated with MoloVol

MoloVol can calculate various types of volumes and surface areas of a chemical structure by “rolling”
probes around atoms. The probe may for instance represent the solvent to determine the effective
volume and surface area of a molecule.

When several isolated spaces can be occupied by a probe, they are listed separately in decreasing
order of volume as “cavities”.

Volumes and surface areas calculated with MoloVol can be visualized by exporting isosurface maps
that can be viewed in PyMOL, Chimera and ChimeraX (see 2.7.3).

By default, the chemical structure is analyzed in an empty space but there is an option to analyze a
crystallographic unit cell by taking into consideration atoms in the neighboring unit cells (see 2.5.2).

There are two main calculation modes using either one probe or two probes of different sizes.

3
 2.1.1. Single-probe mode

In the figure above, the probe could reach three separate portions of the space: cavities #1, #2 and the
outside space. The Connolly surface for the outside space is the molecular open surface.

Calculation in single-probe mode can provide

- van der Waals volume (Vvdw, orange)

- probe excluded void volume (Vvoid, grey) which corresponds to empty space around the chem-
ical structure that is inaccessible to atoms and molecules of the same size as the probe or
larger
- probe accessible volume (Vcore, blue) which corresponds to the space that the core of the probe
can reach
- probe shell volume (Vshell, green) which corresponds to the layer of one probe radius thickness
around the molecule
- probe occupied volume (Vocc = Vcore + Vshell, blue + green) which corresponds to the space that
the entire probe can reach
- molecular volume (Vmol = Vvdw + Vvoid, orange + grey) which corresponds to the effective volume
occupied by the chemical structure
- molecular volume with isolated cavities (Vmol-isolated = Vmol + Vocc-isolated-cavities) which corresponds
to the volume occupied by the chemical structure inaccessible from the outside
- van der Waals surface area (Svdw, red line)
- probe accessible surface area (Sacc, blue line) which corresponds to the surface accessible by
the core of the probe, similar in concept to the Lee-Richards surface (solvent accessible surface
area or SASA)
- probe excluded surface area (Sexc, green line) which corresponds to the effective molecular
surface, similar in concept to the Connolly surface
- molecular open surface area (Smol-open) which corresponds to the surface area that is only open
to the outside and encloses Vmol-isolated

Each probe related volume and surface area will be given in total value. Each cavity is characterized by
an individual Vcore, Vocc, Sacc and Sexc.

4
Note that in this single-probe mode without unit cell analysis, the space outside the chemical structure
(+ any connected pocket and tunnel) does not have a defined volume value. To analyze pockets and
tunnels, or define the “outside” space, use the two-probe mode and/or crystal unit cell analysis.

When probe shell volumes from different cavities are touching, they are separated based on the near-
est probe core volume detected. In the figure above, dashed lines represent the boundary between
cavity #2 and the outside space. Accordingly, this boundary surface area is included in both cavity #2
and outside space probe excluded surface areas but not in the total probe excluded surface area.

2.1.2. Two-probe mode

The two-probe mode was designed specifically to analyze molecules with internal cavities connected
to the outside such as enzymes, cage compounds or deep cavitands.

There is no absolute difference between the inside and outside of a molecule for a probe that can
freely go in and out of the molecule via large gaps. Thus, this mode can be used to define the outside
space by choosing a large probe that cannot access the inside of the molecule. A small probe is then
used to explore the remaining space not accessible by the large probe.

While the small probe often represents a meaningful physical object like a hydrogen atom or a mole-
cule of water, the large probe radius will likely be selected arbitrarily to separate the inside and outside
of a hollow molecule. Results derived from calculations with arbitrary parameters do not have physical
meaning and are merely indicative.

In addition to the values calculated in single-probe mode (see 2.1.1), this mode also provides the large
probe core (dark pink) and shell (yellow) volumes as well as the molecular surface area defined by
both probes excluded surface (combination of green and black lines).

Note that in the above figure, cavities #3 and #4 are connected to the outside. In this mode, cavities
are further attributed a type based on the number of entrances from the outside: isolated for 0, pocket
for 1, or tunnel for more than 1 entrance.

5
 2.1.3. Example of calculation result

Analyzing a cage compound with an open cavity can provide the van der Waals, probe excluded and
probe accessible volumes and surface areas in single-probe mode while the two-probe mode can serve
to define the limits of the cavity and give the volumes and surfaces areas specific to the cavity.

For structures with isolated internal cavities such as a fullerene C60, the single-probe mode directly
provides the volume and surface information for the molecule and the cavities. In such cases, the two-
probe mode is superfluous.

For the above figure, the input structure was rendered with PyMOL and the surfaces resulting from
the calculation were rendered with ChimeraX (see 2.7.3).

More practical examples are given in section 3.

6
 2.2. Graphic user interface

The input panel contains all the file loading and calculation parameter options.

The left side of the input panel is devoted to file loading and reading. A default element properties file
is provided but can be changed if needed (see 2.6.2). After loading a valid structure file (see 2.6.1 and
2.5.1), the elements found in the structure will be displayed in the elements list table. The user can
include or exclude elements and change manually their radius in this table if needed.

The right side of the input panel contains a list of parameters that can be adjusted to the user needs
before starting the calculation (see 2.3). Once the Calculate button is pressed, the calculation can be
monitored via the Progress bar (below the Calculate button) and Status bar (bottom of the window).
Note that Progress bar does not represent the total calculation progress but each stage of the calcula-
tion (2 to 5 depending on parameters). If the calculation takes too long or wrong parameters were
used, the Abort button allows to stop the calculation. It should stop almost instantaneously but can
take few seconds in some cases.

Once the calculation is completed, a summary of the results is displayed in the output panel. Total
volumes and surface areas are provided on the left while separate probe accessible voids are listed on
the right as “cavities”.

A report containing all parameters and detailed results as well as surface maps to visualize the volu-
metric objects and surfaces calculated can be exported via the export buttons. Alternatively, the user
can tick Auto export options before starting the calculation to generate the files at the end of the
calculation. For more details, see section 2.7.

7
 2.3. Command line interface

MoloVol can be used entirely from the command line (a.k.a. shell, terminal). The command line inter-
face can be used for writing scripts that conduct many calculations in sequence.

To use MoloVol the command line interface, first locate the executable. Where to find the executable
may depend on your operating system and on your installation. In macOS the executable is hidden
inside the appbundle.
$ /Applications/MoloVol.app/Contents/MacOS/MoloVol

On Ubuntu or Debian, the installer makes the “molovol” command directly accessible.
$ molovol

On Windows, the executable will be located where you unzip it. It can then be freely moved or copied
to any directory. The inputfile folder should remain in the same directory as the executable.

Running the executable will open the graphic user interface (GUI). To suppress the GUI, simply use a
switch such as the version switch (--version or -v) or the help switch (--help or -h).
$ molovol -v
Version: 1.1.0

To start any calculation, you need to at least specify three options: the small probe radius (-r), the
grid resolution (-g), and the structure file (-fs). You can call the three switches in any order, and you
need to follow each on with the appropriate argument. When using file or directory arguments, you
may use absolute or relative paths.
$ molovol -r 1.2 -g 0.2 -fs ./inputfile/example_C60.xyz

There are several switches, some of which require arguments. Those that do not require an argu-
ment are binary switches that are off by default. Each switch has a verbose and a short version. They
are summarized in the table below.

You may notice that there is no switch to enable two-probe mode. You can enable two-probe mode
by using both the small probe radius (-r) and the large probe radius (-r2) switches simultaneously.
$ molovol -r 1.2 -g 0.2 -fs ./inputfile/example_C60.xyz -r2 3

To export the calculation report or any surface map file, you will need to both enable the appropriate
switch and specify the output directory (-do). Note: the output directory should already exist.
$ molovol -r 1.2 -g 0.2 -fs ./inputfile/example_C60.xyz -xr -do ./re-
sults

While the calculation is running, you are continuously updated on the progress before the results are
displayed. You can silence the progress update with the quiet switch (-q), and you can adjust which
results to output in your shell with the output switch (-o). The output switch is followed by a list of
comma-separated display options. The options are listed in the table below.
$ molovol -r 1.2 -g 0.2 -fs ./inputfile/example_C60.xyz -q -o depth,vol

8
 Option Display

none Suppress all output

inputfile Display structure file path

resolution Display grid resolution

depth Display octree depth

radius_small Display (small) probe radius

radius_large Display large probe radius

input Display all user input parameters

hetatm Display "Include HETATM" option

unitcell Display "Analyze unit cell" option

probemode Display whether two-probe mode is enabled

surface Display whether surface area calculation is enabled

options Display all binary user options

formula Display sum formula of molecule/structure

time Display calculation time

vol_vdw Display van der Waals volume

vol_inaccessible Display inaccessible volume

vol_core_s Display core volume of small probe

vol_shell_s Display shell volume of small probe

vol_core_l Display core volume of large probe

vol_shell_l Display shell volume of large probe

vol Display all volumes

surf_vdw Display van der Waals surface

surf_mol Display molecular surface

surf_excluded_s Display (small) probe excluded surface

surf_accessible_s Display (small) probe accessible surface

surf Display all surfaces

cavities Display cavity data

all Display all, default option

9
Switch Verbose Description Argument

-h --help Display help for CLI none

-v --version Display the app version none

-r --radius (Small) probe radius Decimal num-

ber

-g --grid Spatial resolution of the underlying grid Integer

-fs --file-structure Path to the structure file Path

-fe --file-elements Path to the elements file Path

(default: preprogrammed path)

-do --dir-output Path to the directory output Path

-r2 --radius2 Large probe radius, also enables two-probe mode Decimal num-
ber

-d --depth Octree depth (default: 4) Integer

-ht --hetatm Include HETATM from pdb file none

-uc --unitcell Analyze unit cell none

-df --surface Calculate surface areas none

-xr --export-report Export report (requires: -do) none

-xt --export-total Export total surface map (requires: -do) none

-xc --export-cavities Export surface maps for all cavities (requires: -do) none

-o --output Control what parts of the output to display (de- none

fault: all)

-q --quiet Silence progress resporting none

-un --unicode Allows unicode output (only works for some shells) none

10
 2.4. Web app

MoloVol has been made available through a web app. This way, MoloVol can be used using any desktop
browser via the link http://app.molovol.com/

The web app is a convenient way to use MoloVol without having to download and install the desktop
version. This can be useful if users want to try out the software before installing it, if the structures are
small enough to not require large amounts of processing power, or if users would like to use MoloVol
but lack computing power.

Note that some minor features from the desktop version are not available in the web app.

2.5. Parameters and options

2.5.1. Include HETATM

This option is only available after loading a PDB structure file.

Protein data bank (PDB) files are designed for biomolecules. In these files, the atoms belonging to the
biomolecule structure are labelled ATOM and others atoms are labelled HETATM (for hetero atom). If
you are not analyzing a biomolecule structure, it is advised to include HETATM by turning this option
on because the whole structure to be analyzed might be labelled as HETATM.

To exclude HETATM, untick the box and reload the files with the Reload button.

2.5.2. Analyze crystal unit cell

This option is only available after loading a PDB or CIF structure file.

When this option is turned off, MoloVol will model the input structure in a void space.

When this option is turned on, MoloVol will

1) Apply the symmetry elements corresponding to the space group of the input structure.
2) Generate a supercell to analyze the surrounding environment of the unit cell.
3) Orthogonalize the unit cell to perform calculations in a rectangular parallelepiped.
4) Return volume, surface area and surface maps (according to selected options) limited to the
unit cell only.

If this option is activated and a calculation report is exported (see 2.7), MoloVol will generate two XYZ
files containing the structure in the orthogonalized unit cell and the partial supercell used to run cal-
culations. WARNING: The PDB format does not contain all information related to some space groups.
It is highly recommended to check that these generated structures are comparable to the input struc-
ture. In case of a doubt, CIF files are preferred as they contain all symmetry data.

Depending on the position of molecules in the unit cell, some molecules and cavities as seen in the
surface maps might be fragmented (i.e., cut by the boundaries of the orthogonalized unit cell). In such
cases, the user will have to check the surface maps to know what cavities are fragmented and manually
add up the volume and surface area values of the fragments.

2.5.3. Calculate surface area

When this option is turned on, MoloVol will calculate surface areas of the volumetric objects analyzed
(e.g., molecules, cavities) in addition to the volumes that are calculated by default.

11
If surface areas are not needed, it is advised to keep this option turned off since this option increases
calculation time.

2.5.4. Enable two-probe mode

When this option is turned on, MoloVol will use two spheres of different sizes to probe the void space
around atoms. As described in section 2.1.2, this mode is designed to define the limit of open cavities
(often named pockets or tunnels for biomolecules) from the external void space. Additionally, the cav-
ities will be attributed a type based on the number of openings (isolated for 0; pocket for 1; tunnel for
more than 1). This mode can be particularly useful to calculate the “inner” cavity volume of open mo-
lecular cages and cavitands.

It is advised to keep this option turned off if it isn’t necessary since this option increases calculation
time (especially with very large second probe).

2.5.5. Small probe radius

Set the radius of the main probe (small probe in two-probe mode (see 2.5.4)).

List of suggested radii for specific calculations (available in the drop-down menu):

- 1.2 Å (default, vdw radius of hydrogen), will detect cavities accessible by hydrogen atoms.
- 0 Å, useful if only the vdw volume of the molecule is needed. This zero probe radius will con-
siderably reduce calculation time.
- 1.4 Å, this is the approximate radius of water typically used in biomolecule analysis programs.
It was derived from the O–O distance of ~2.8 Å observed in ice. The physical meaning of this
value to model a solvent probe in liquid water is debatable but it is convenient to compare
results with reported volume and surface area values based on this probe radius.
- 1.66 Å (vdw radius of nitrogen), useful to compare to N2 sorption measurements.
- 1.86 Å (spherical radius of N2), useful to compare to N2 sorption measurements.
- 1.83 Å (vdw radius of argon), useful to compare to argon sorption measurements.

Notes: (i) These element vdw radii come from a study by S. Alvarez (Dalton Trans. 2013, 42, 8617-8636.
https://doi.org/10.1039/C3DT50599E ) but may differ from other references. (ii) The “N2 spherical ra-
dius” is reported in https://doi.org/10.1021/acs.langmuir.7b01682 and can be convenient for calcula-
tions but does not have any physical meaning.

Calculation time will increase cubically with the ratio small_probe_radius/grid_resolution. It is highly
recommended to keep this ratio below 100 (preferably below 30) to maintain short calculation times.
If an excessively large probe is needed for a specific calculation, it is advised to think carefully about
the optimal grid resolution to maintain reasonable calculation time.

2.5.6. Large probe radius

Set the radius of the large probe in two-probe mode (see 2.5.4).

The large probe must be larger than the small probe, otherwise the program will prompt the user to
change probes radii.

Calculation time will increase cubically with the ratio large_probe_radius/grid_resolution. It is highly
recommended to keep this ratio below 100 (preferably below 30) to maintain short calculation times.
It is therefore advised to test smaller radii and increase gradually if the result does not meet the user
expectations.

12
 2.5.7. Grid resolution
The grid resolution represents the size of voxels used for the calculation. By default, the grid resolution
is set to 0.2 Å which is a decent resolution for testing. A resolution of 0.1 Å should be suitable for most
publication quality calculations. A larger value corresponds to a lower resolution. The accuracy of sur-
face areas is more affected by the grid resolution than volumes (see details in the scientific article,
section 1.2). Thus, it is strongly recommended to use a grid resolution of 0.1 Å or smaller to obtain
accurate surface areas.

Calculation time will increase cubically with the ratio probe_radius/grid_resolution. It is highly recom-
mended to keep this ratio below 100 (preferably below 30) to maintain short calculation times. It is
therefore advised to run tests with larger grid resolution (0.2–0.5 Å) when optimizing other parameters
such as the probes radii. When all other parameters are optimal, a final high resolution calculation can
be run for an extended time (e.g. 0.1 Å).

The grid resolution will also impact the resolution and file size of the exported surface maps. If the
surface map files generated are too large, it is advised to run one calculation with a larger grid resolu-
tion to generate surface maps of a more reasonable size.

2.5.8. Optimization depth

This parameter only affects calculation time and not the results. It is not recommended to change the
default value (i.e., 4) unless the user fully understands the effect of this parameter and needs to change
it.

MoloVol was coded with an algorithm to accelerate calculations. An optimization depth of 0 means no
algorithmic acceleration.

Excessively large optimization depths are counterproductive and decrease the calculation time past an
optimal value. The default value should be close to the optimal value considering typical chemical
structures and calculation parameters.

For more details on details on how the acceleration algorithm works, see section 1.3.

2.6. Input files

2.6.1. Chemical structure

MoloVol accepts three types of chemical structure file formats as input: crystallographic information
file (.cif), protein data bank (.pdb) and XYZ (.xyz).

Detailed information about these file formats can be found at:

- CIF: https://www.iucr.org/resources/cif/spec/version1.1
- PDB: https://www.wwpdb.org/documentation/file-format
- XYZ: http://openbabel.org/wiki/XYZ_%28format%29

If an unknown element (e.g., symbol A) is detected in the structure, it will be listed in the user interface
(see section 2.1) but excluded from the calculation by default. If the user wishes to include such custom
elements, it will be necessary to check the include box for the element and provide a radius in the user
interface before starting calculation. Element with radius 0 will be discarded during calculation.

13
For crystallographic unit cell analysis, only PDB and CIF files are accepted. Make sure that the proper
crystallographic information is present in the PDB file (open with a text editor and check if there is a
line starting with CRYST1 followed by the unit cell parameters and the space group).

Several variations of the .xyz file format exist. Only the basic XYZ format can be read by MoloVol. If
unsure, export the structure to “XMol (.xyz)” format from the Mercury program – freely distributed by
The Cambridge Crystallographic Data Centre (CCDC). The .xyz files exported from the Chem3D program
(i.e., Tinker MM2 and MM3 Input format) are incompatible with MoloVol.

If the structure is not or partially recognized by MoloVol, please check with a text editor that the input
structure file follows the format as detailed in the links provided above.

Examples of valid CIF, PDB and XYZ files are provided with the program in the inputfile folder. The
structure is a model of fullerene C60.

2.6.2. Element properties

A default file for element radii (elements.txt) is provided with the program and located in the inputfile
folder. The element radii given in this file correspond either to van der Waals radii or ionic radii for
charged elements. Van der Waals radii were taken from the publication “A cartography of the van der
Waals territories” (S. Alvarez, Dalton Trans. 2013, 42, 8617–8636.
https://doi.org/10.1039/C3DT50599E ). Ionic radii were taken from the website http://abu-
lafia.mt.ic.ac.uk/shannon/ptable.php providing data from the publication “Revised effective ionic radii
and systematic studies of interatomic distances in halides and chalcogenides” (R. D. Shannon, Acta
Cryst. A 1976, 32, 751–767. https://doi.org/10.1107/S0567739476001551 ). The atomic weights were
taken from IUPAC data (J. Meija et al., Pure Appl. Chem. 2016, 88, 265–291.
https://doi.org/10.1515/pac-2015-0305 ).

The user can manually change radii within the program if desired (see section 2.2). Alternatively, the
user can also prepare a custom element properties file if the default values do not match the needs of
the user.

The simplest way to create such an alternative element properties file is to make a copy of the default
file provided and change the radius values where necessary. Custom elements can be added to meet
the user needs (e.g., isotopes). It is advised to use a maximum of two alphabetic characters for the
custom element symbols as PDB files only consider two characters for the element symbol. Yet, if XYZ
or CIF structure files are provided as input, MoloVol allows the use of longer symbols made of alpha-
betic characters and charges (we recommend less than 5 characters for readability, e.g. Fe2+).

2.6.3. Crystallographic space groups

A file containing all crystallographic space group symmetry elements (space_groups.txt) is provided
with the program and located in the inputfile folder. This file is necessary for the unit cell analysis
option with PDB files and should not be moved to another folder or modified.

2.7. Exporting and reading results

2.7.1. Manual exportation

After completion of the calculation, the user can use buttons in the export panel (see 2.2) to export
the report, the total surface map and a list of surface maps for each separate cavity. The user can select
the name of the file to be exported.

14
WARNING: selecting the name of an existing file will overwrite this file. Please be careful when enter-
ing a file name.

2.7.2. Automatic export

It is possible to automatically export the report and surface maps upon completion of the calculation.
To do so, it is necessary to activate the corresponding options and provide a save directory in the
export panel (see 2.2) before starting the calculation.

The files exported will be given a name based on the structure file name and parameters. Running a
calculation with the same structure file name and parameters will overwrite previous files.

2.7.3. Visualizing isosurfaces

Volumetric maps are generated in OpenDX format (.dx). They serve to visualize isosurfaces at the
boundary of volume types and are thus referred as “surface maps”. These files can be opened with the
chemistry-related programs PyMOL, Chimera and ChimeraX. Note that other programs might be com-
patible but we only document the above three programs here.

The different types of surfaces (e.g., vdw, molecular, probe accessible) can all be visualized from a
single file. To do so, select different isosurface levels in the visualizing program of choice (see below
for detailed procedure).

The list of surfaces and corresponding isosurface levels are provided in the report of the calculation
and below:

For single-probe mode:

Level 0.5 : Van der Waals surface

Level 2.0 : Molecular and cavity surface (probe excluded, similar to the Connolly surface)
Level 5.0 : Probe accessible surface (similar to the Lee-Richards molecular surface)

For two-probe mode:

Level 0.5 : Van der Waals surface

Level 1.5 : Molecular surface (both probes excluded, similar to the Connolly surface)
Level 3.0 : Isolated cavities, pockets and tunnels (small probe excluded, similar to the Connolly
surface but only 'inside')
Level 5.0 : Small probe accessible surface (similar to Lee-Richards molecular surface but only 'in-
side')

15
Visualize surface maps in PyMOL

Select A (action) then choose how to

display the isosurface (as a mesh or
as a solid surface) then select a start-
ing level (e.g., 2.0)

To further modify the

level, click on A then
level for the mesh ob-
ject that was created.

You can open multiple surface maps (e.g., different “cavities”) then change colors, transparency and
other parameters independently.

16
For more information, check https://pymolwiki.org/index.php/Isomesh and https://pymol-
wiki.org/index.php/Isosurface

It is also possible to load the original chemical structure and display cavities along the structure to
make visually appealing figures such as the structures in section 3 or the fullerene below.

Transparent cavity Sexc Transparent fullerene C60 backbone

Note: PyMOL uses default element radii that may differ from the radii used in a MoloVol calculation.
To visualize structures in PyMOL with the same element radii than the ones used in a MoloVol calcu-
lation, the report from MoloVol provides a set of commands to change the element radii in PyMOL.
After opening the structure in PyMOL, simply paste the set of commands in the command prompt of
PyMOL (all lines can be copy/pasted at once).

Warning: If the original structure file contains explicit ions, the report of MoloVol will provide com-
mands with the charge such as
alter (elem Fe2+),vdw=0.78

but PyMOL only uses alphabetic characters for element symbols. Therefore, it is necessary to remove
the charges from the command:
alter (elem Fe),vdw=0.78

If the same element is present in more than one oxidation state with different radii in the structure, it
will be necessary to manually select the atoms in PyMOL to set different radii.

17
Visualize surface maps in Chimera

From Chimera, go to
Tools
=> Volume Data
=> Volume Viewer

In this new Volume Viewer window, there are several options to visualize the isosurfaces.

Map files can be opened from the main Chimera window or from the Volume Viewer window.

Enter the desired Resolution ratio (best to keep it

isosurface level to 1 for the original resolution)

You can open multiple surface maps (e.g., different “cavities”) then change colors, transparency (from
Features drop-down menu) and other parameters independently.

18
For more information, check https://www.cgl.ucsf.edu/chimera/docs/ContributedSoft-
ware/volumeviewer/volumeviewer.html

Note: Chimera uses default element radii that might differ from the radii used in a MoloVol calculation.
To change element radii in Chimera, follow instructions found in this user guide:
https://www.rbvi.ucsf.edu/chimera/docs/UsersGuide/midas/vdwrad.html

Visualize surface maps in ChimeraX

ChimeraX is a more advanced version of Chimera and thus works similarly. To display isosurfaces, open
the Volume Viewer that will show in the right panel.

For more information, check https://www.cgl.ucsf.edu/chimerax/docs/user/tools/volumeviewer.html

Note: ChimeraX uses default element radii that may differ from the radii used in a MoloVol calculation.
To change element radii in ChimeraX, follow instructions found in this user guide:
https://www.cgl.ucsf.edu/chimerax/docs/user/commands/size.html

19
 3. Calculation examples and results analysis
3.1. Open cage with wide gaps

If we consider an octahedral Pd6L4(bipy)4 octahedral cage (Yoshizawa et al., J. Am. Chem. Soc. 2005,
127, 2798–2799. https://doi.org/10.1021/ja043953w), we can see a significant difference in cavity vol-
ume between single-probe and two-probe calculations. In single-probe calculations, a large probe is
necessary to define a cavity because small probes can exit via the wide openings of the cage. Conse-
quently, the fine details in the asperities of the cavity are not probed and the cavity volume is under-
estimated. In contrast, the two-probe mode detects these fine details.

Single-probe mode Cavity shape difference be- Two-probe mode

Probe radius: 3.3 Å tween single- and two- Small probe radius: 1.2 Å
Grid resolution: 0.1 Å probe modes Large probe radius: 5.0 Å
Cavity volume (Vocc): 443 Å3 51% volume increase! Grid resolution: 0.1 Å
(smaller probes can exit) Cavity volume (Vocc): 669 Å3

3.2. Deep cavitand

Cavitands are compounds that commonly presents a concave cavity with a wide opening. In such struc-
tures, a single-probe cannot define a cavity as the probe can always exit the cavity. A two-probe cal-
culation can, however, easily define a cavity that makes sense from a human perspective. As an exam-
ple, a resorcinarene-based deep cavitand is shown below (Amrhein et al., J. Am. Chem. Soc. 2002, 124,
10349–10358. https://doi.org/10.1021/ja0204269).

Two-probe mode
Small probe radius: 1.2 Å
Large probe radius: 3.0 Å
Grid resolution: 0.1 Å
Cavity volume (Vocc): 295 Å3

20
 3.3. Open macrocycle

Macrocycles with extended edges present a cavity (e.g., cyclodextrins, cucurbiturils, calixarenes, pil-
lararenes). Like in the case of a deep cavitand (see section 3.2), these macrocycles commonly present
wide openings preventing single probes to define a cavity. A two-probe calculation can, however, easily
define a cavity that makes sense from a human perspective. As an example, a pillararene derivative is
shown below.

Li et al., Angew. Chem. Int. Ed. 2020, 59, 22012–22016. https://doi.org/10.1002/anie.202010802

Two-probe mode
Small probe radius: 1.2 Å
Large probe radius: 3.0 Å
Grid resolution: 0.1 Å
Cavity volume (Vocc): 189 Å3

3.4. Giant open cage

Giant cages such as the Pd48L96 coordination cage below present wide gaps (Fujita et al., Nature 2016,
540, 563–566. https://doi.org/10.1038/nature20771). Two-probe mode can be used to define a cavity
but would be extremely demanding in computational resources due to the excessively large second
probe needed to define the outside space (reminder: the large probe must be large enough to not fit
in the cavity). In such cases, it is recommended to use the single probe mode that is less demanding
and still provide a decent cavity volume because the asperities that are not detected have a negligeable
volume compared to the bulk of the cavity.

Single-probe mode
Probe radius: 6.0 Å
Grid resolution: 0.2 Å
Cavity volume (Vocc): 86 526 Å3

21
 3.5. Crystalline porous materials

Crystalline porous materials mostly comprise metal-organic frameworks (MOFs) and covalent organic
frameworks (COFs). They are often characterized with gas sorption measurements (such as N2 at 77 K
or Ar at 87 K). From the gas sorption isotherms, the surface area and total pore volume are calculated
and reported. It can be useful to compare the theoretical values with experimental values to determine
the quality of the material prepared. MoloVol can provide these theoretical values.

Experimental surface areas are commonly calculated based on the BET (Brunauer–Emmett–Teller) or
Langmuir adsorption models. Both correspond to MoloVol’s accessible surface area (Sacc) for a probe
with the same radius as the adsorbed gas provided that the pores in the material are large enough to
accommodate several gas atoms/molecules (see below for more details). The total pore volume cor-
responds to the probe occupied volume (Vocc). Calculated BET surface area can vary depending on sev-
eral parameters, more information and a program to calculate them are described in Osterrieth et al.,
Adv. Mater. 2022, 34, 2201502. https://doi.org/10.1002/adma.202201502

Note that defects in the structure or chemicals stuck in the pores can greatly affect the surface area
and pore volume (either increase or decrease). Example of controlled defect in the MOF UiO-66 to
modify surface area and pore volume: Wu et al., J. Am. Chem. Soc. 2013, 135, 10525–10532.
https://doi.org/10.1021/ja404514r

Calculated values should ideally match experimental values for materials of high quality with suffi-
ciently large pores. It is important to remember that MoloVol works with a static hard sphere model.
Real materials can have dynamic aspects that lead to fluctuation in porosity such as the accessible pore
network for an adsorbate. Moreover, some adsorbates are not spherical. For example, N2 shape is
more cylindrical or ellipsoidal than spherical. Finally, microporous materials with very narrow pores
don’t follow the BET model and experimental BET surface area may significantly differ from theoretical
Sacc even for highly crystalline materials (e.g. pores cannot accommodate enough gas particles to probe
the entire surface, see more details in see https://doi.org/10.1515/pac-2014-1117,
https://doi.org/10.1021/ja071174k, and https://doi.org/10.1016/S0167-2991(07)80008-5).

For materials with large pores such as IRMOF-10 below (Eddaoudi et al., Science 2002, 295, 469–472.
https://doi.org/10.1126/science.1067208), standard calculations can be performed without issue and
give a realistic accessible surface Sacc that should match the BET surface area.

IRMOF-10 model
Single-probe mode
Probe radius: 1.86 Å (N2 spherical radius)
Grid resolution: 0.1 Å
Sacc: 4860 m2/g
Vocc: 2.59 cm3/g

22
However, for materials presenting narrow pores such as MOFs UiO-66 and HKUST-1, some problems
may arise. Using probes of the average spherical radius of N2 (1.86 Å) leads to fragmented pore net-
works (several cavities detected by MoloVol) while using the atomic radius of N (1.66 Å) leads to a
complete single pore network (a single cavity reported). This shows the importance of visualizing and
understanding the results. They need to make sense and match the expected physical property.

The UiO-66 case is presented below. Both calculations are performed in single probe mode with crystal
unit cell analysis and grid resolution of 0.1 Å. The crystal structure comes from Valenzano et al., Chem.
Mater. 2011, 23, 1700–1718. https://doi.org/10.1021/cm1022882 but was modified to add hydrogen
atoms that were missing from the original structure.

Reported BET surface area: 1090 m2/g

Reported total pore volume: 0.44 cm3/g
J. Am. Chem. Soc. 2013, 135, 10525–10532. https://doi.org/10.1021/ja404514r

Probe radius: 1.66 Å (N radius) Probe radius: 1.86 Å (N2 spherical radius)
One pore network Fragmented cavities
Sacc: 1158 m2/g Sacc: 851 m2/g
Vocc: 0.38 cm3/g Vocc: 0.36 cm3/g
Good match with experimental values Differs significantly from experimental values

Remark: In images of porous materials, the accessible surface is displayed to show the pore
connectivity in contrast with the cage and macrocycles examples above in which the excluded surface
(Sexc) is displayed to represent the cavity volume (Vocc).

Recommendations for MoloVol calculations of porous material crystal structures

The input structure for MoloVol should ideally contain the hydrogen atoms that are regularly omitted
from crystal structures but not the free solvent molecules (unless they are strongly bound to the struc-
ture like coordinated to metal centers).
In most cases with large pores, MoloVol calculations with probes of the spherical radius of N2 (1.86 Å)
will provide results usable to compare to experimental values of nitrogen sorption. It is advised to start
with that parameter in rapid calculations at a resolution of 0.2 or 0.3 Å then, if results are satisfactory,
run a longer and more precise calculation at a resolution of 0.1 Å. If results are unsatisfactory (e.g.,
pore fragmented in isolated cavities not reflecting the porous nature of the material), parameters need
to be adjusted like in the UiO-66 example above.

23