Command line interface

The command line interface (CLI) for ᴍᴏʀғᴇᴜs is powered by Python Fire. In this way, allmost all of the functionality of the module system is made available also in the command line.

Introduction

The entry point to the CLI is the command line script morfeus. Running this command in the terminal gives a help page with all the possible subcommands.

Input 1

$ morfeus

Output 1

NAME
  morfeus

SYNOPSIS
  morfeus COMMAND

COMMANDS
  COMMAND is one of the following:

   buried_volume
     CLI for buried volume.

   cone_angle
     CLI for cone angle.

   conformer
     CLI for cone angle.

   dispersion
     CLI for dispersion descriptor.

   local_force
     CLI for local force.

   pyramidalization
     CLI for pyramidalization.

   sasa
     CLI for solvent accessible surface area.

   sterimol
     CLI for Sterimol.

   visible_volume
     CLI for visible volume.

   xtb
     CLI for XTB.

There is also a help page for each subcommand:

Input 2

$ morfeus sterimol -- --help

Output 2

NAME
    morfeus sterimol - CLI for Sterimol.

SYNOPSIS
    morfeus sterimol FILE

DESCRIPTION
    CLI for Sterimol.

POSITIONAL ARGUMENTS
    FILE
        Type: str
        Geometry file

NOTES
    You can also use flags syntax for POSITIONAL ARGUMENTS

All the subcommands serve as entry points to the corresponding Python classes used in the module system. For example, morfeus sterimol tBu.xyz - creates a partially instantiated Sterimol object where the elements and coordinates arguments have been set from the geometry file. To find out what other argument can be given to this object, we run

Input 3

$ morfeus sterimol tBu.xyz - -- --help

Output 3

NAME
    morfeus sterimol tBu.xyz - partial(func, *args, **keywords) - new function with partial application of the given arguments and keywords.

SYNOPSIS
    morfeus sterimol tBu.xyz - GROUP | COMMAND | --dummy_index=DUMMY_INDEX --attached_index=ATTACHED_INDEX <flags>

DESCRIPTION
    partial(func, *args, **keywords) - new function with partial application of the given arguments and keywords.

ARGUMENTS
    DUMMY_INDEX
        Type: int
    ATTACHED_INDEX
        Type: typing.Union[int, ...

FLAGS
    --radii=RADII
        Type: Optional[typing.Union[int, float, complex, str, bytes, numpy.ge...
        Default: None
    --radii_type=RADII_TYPE
        Type: str
        Default: 'crc'
    --n_rot_vectors=N_ROT_VECTORS
        Type: int
        Default: 3600
    --excluded_atoms=EXCLUDED_ATOMS
        Type: Optional[t...
        Default: None
    --calculate=CALCULATE
        Type: bool
        Default: True

GROUPS
    GROUP is one of the following:

     args

     keywords

COMMANDS
    COMMAND is one of the following:

     func
       Performs and stores results of Sterimol calculation.

We learn that we need to supply the two arguments: dummy_index and attached_index. Optional keyword arguments can also be given. After supplying the additional arguments, we get back a fully instantiated object. Getting the help from this object returns the available commands and what values are available.

Input 4

$ morfeus sterimol tBu.xyz - 1 2 --radii_type=bondi - -- --help

Output 4

NAME
    morfeus sterimol tBu.xyz 1 2 --radii_type=bondi - Performs and stores results of Sterimol calculation.

SYNOPSIS
    morfeus sterimol tBu.xyz - 1 2 --radii_type=bondi - COMMAND | VALUE

DESCRIPTION
    Performs and stores results of Sterimol calculation.

COMMANDS
    COMMAND is one of the following:

     bury
       Do a Buried Sterimol calculation.

     calculate
       Calculate Sterimol parameters.

     draw_3D
       Draw a 3D representation of the molecule with the Sterimol vectors.

     print_report
       Prints the values of the Sterimol parameters.

     set_points
       Set points for calculation of Sterimol.

     surface_from_radii
       Create surface points from vdW surface.

VALUES
    VALUE is one of the following:

     B_1

     B_1_value

     B_5

     B_5_value

     L

     L_value

     L_value_uncorrected

     bond_length

We could for example access the B_1_value attribute or run the method print_report with the verbose=True keyword argument.

Example of Sterimol CLI

$ morfeus sterimol tBu.xyz - 1 2 --radii_type=bondi - B_1_value
2.964748534441907
$ morfeus sterimol tBu.xyz - 1 2 --radii_type=bondi - print_report
L         B_1       B_5
4.31      2.96      3.37

The last command correspond to the following Python code using the module system.

Example of Sterimol with module code

from morfeus import read_geometry, Sterimol
elements, coordinates = read_geometry("tBu.xyz)
sterimol = Sterimol(elements, coordinates, 1, 2, radii_type="bondi")
sterimol.print_report(verbose=True)

Detailed use

Positional arguments are passed in sequence separated by spaces, for example:

$ morfeus sterimol tBu.xyz - 1 2

Keyword arguments are passed with or without an equals sign, so both of these commands give the same result:

$ morfeus sterimol tBu.xyz - 1 2 --radii_type=bondi
$ morfeus sterimol tBu.xyz - 1 2 --radii_type bondi

A single - is used to indicate that all arguments have been provided and the function/class should be evaluated. For example, the - before print_report in the example below tells Fire to instantiate the Sterimol class, as we don’t want to give more keyword arguments. Then the print_report method is excuted.

$ morfeus sterimol tBu.xyz - 1 2 --radii_type bondi - print_report

Arguments following the -- separator go directly to the Fire program. For example, the -- in the line below makes sure that --help is sent to Python Fire instead of the Sterimol object.

$ morfeus sterimol tBu.xyz - -- --help

Partial initialization

ᴍᴏʀғᴇᴜs uses Fire together with functools.partial to partially initialize classes using the information in the geometry file. When running morfeus sterimol tBu.xyz -, this is what goes on behind the scenes:

cli function for Sterimol

def cli(file: str) -> Any:
    elements, coordinates = read_geometry(file)
    return functools.partial(Sterimol, elements, coordinates)

The geometry file is read, and the elements and coordinates are used to partially instantiate a Sterimol object. By specifiying the final hyphen -, we are telling Fire to evaluate the cli function and return this partially instantiated object. We can can then supply the remaining arguments required to fully instantiate Sterimol with morfeus sterimol tBu.xyz - 1 2 -.

Chaining

A very powerful feature of Fire is chaining, which allows a series of commands to be run on the same object. The commands (and their arguments) are separated by hyphens, and the chain should end with a command that gives some output. Here is one example where we create an electron density isosurface from a cube file for a dispersion descriptor calculation.

$ morfeus dispersion corannulene.xyz - --point_surface=False - surface_from_cube corannulene.cub - compute_p_int - print_report
Surface area (Ų): 248.0
Surface volume (ų): 247.8
P_int (kcal¹ᐟ² mol⁻¹ᐟ²): 25.8

This works because methods that modify Dispersion return the object itself:

def surface_from_cube(self, ...):
    ...
    return self

We can break down the chaining in detail:

morfeus dispersion corannulene.xyz -

Partially instantiate the Dispersion object

--point_surface=False -

Give the keyword argument point_surface=True and fully instantiate

surface_from_cube corannulene.cub -

Run surface_from_cube method with cube filename as argument and return same object

compute_p_int -

Run compute_p_int method and return same object

print_report

Run print_report method and return output

Interactive mode

Another powerful feature of Fire is that it can send the result to an interactive Python session, where it can be manipulated further. This is triggered with the Fire argument --interactive and could be used to, e.g., access the 3D drawing capabilities of ᴍᴏʀғᴇᴜs.

$ morfeus sterimol tBu.xyz - 1 2 - -- --interactive

Fire is starting a Python REPL with the following objects:
Modules: fire
Objects: component, main, morfeus, result, trace

Python 3.9.2 | packaged by conda-forge | (default, Feb 21 2021, 05:02:20)
Type 'copyright', 'credits' or 'license' for more information
IPython 7.22.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]: result
Out[1]: Sterimol(14 atoms)

In [2]: result.bond_length
Out[2]: 1.1

In [3]: result.print_report()
L         B_1       B_5
4.21      2.86      3.27

In [4]: result.draw_3D()
...

Arguments

Fire attemps to correctly guess the correct type of the arguments given in the command line. The following style is recommended as it works across different operating systems. Note that integers being intended as strings need double quotes.

Type	Recommendation
str	bondi, ‘“1”’
int	1
float	1.0
list	‘[1,2]’
dict	‘{“key”: “value”}’
bool	True

Resources

More detailed information on using the CLI can be found in the Fire documentation:

• The Python Fire guide

• Using the CLI

• Specifying arguments