Development#

This section is aimed at developers and advanced users. It briefly explains the wrapper implementation and how to run the tests.

Wrapper implementation#

The necessary code to carry out the linear absorption simulation workflow is included in the COBRAMM engine, which is available independently of the wrapper in the form of some utility scripts.

The wrapper has been developed according to the indications outlined by the SimPhoNy developers. Regarding the solvent, the COBRAMM implementation of the simulation workflow treats this information as a parameter to be chosen among a predefined list of options, specified by their common names. This choice was done because of two reasons. First, the simulation workflow requires the MM parameters for the solvent molecules, and these cannot be generated automatically but require a substantial amount of non-standardizable work. Second, the definition of the solvent molecules is a complex procedure that is done using external tools from the AMBER package, and thus belongs in a substantial measure to the third-party software. In this light, at the level of the wrapper it is not needed to know the molecular structure of the solvent.

The wrapper operates with a minimal ontology (see file cobramm.ontology.yml) that is used to define the inputs and outputs of the wrapper: the molecular structure (a list of atoms each specified by cartesian coordinates and atomic symbol), the name of the solvent, temperature and pressure, the absorption spectrum (a list of absorption values, each considered as a couple wavelength-intensity).

The wrapper is composed of three Python code files:

  • osp/wrapper/cobrammwrapper/simulation_engine.py which is the syntactic layer of the wrapper, i.e. a class that specifies the operations needed to run the simulation workflow in the COBRAMM language.

  • osp/wrapper/cobrammwrapper/cobramm_session.py which is the interoperability layer, that connects the syntactic layer to the OSP-core.

  • examples/simulation_example.py, which is a simple example in which the linear absorption spectrum of a small molecule is computed.

The syntactic layer is further described in detail next. The interoperability layer has been built following the SimPhoNy Wrapper API specification and thus requires no specific description.

Syntactic layer#

The concept behind the CobrammSimulationEngine class that is contained in the syntactic layer is quite simple. It contains a few attributes to store the information coming from the semantic layer:

  • CobrammSimulationEngine.atoms: a dictionary to store the definition of the molecular structure.

  • CobrammSimulationEngine.input_setup: a dictionary to store the other input parameters (temperature, pressure, solvent).

  • CobrammSimulationEngine.accuracy: an integer that specify the accuracy level of the calculation (supposed to be 1, 2 or 3).

  • CobrammSimulationEngine.grid and CobrammSimulationEngine.spectrum: list to store the linear absorption spectrum.

These attributes are set and deleted with appropriate methods (lines 56-71).

56     def add_atom(self, uid, sym, position):
57         """Add or update atom with a given unique identifier,
58         specifying atomic symbol and position (cartesian coordinates)"""
59         self.atoms[uid] = [sym, position]
60 
61     def delete_atom(self, uid):
62         """Delete an atom given its unique identifier"""
63         del self.atoms[uid]
64 
65     def add_property(self, label, value):
66         """Add or update an entry to the input_setup dictionary"""
67         self.input_setup[label] = value
68 
69     def delete_property(self, label):
70         """Delete an entry of input_setup using its unique label"""
71         del self.input_setup[label]

The CobrammSimulationEngine.run method runs the simulation workflow, using the input parameters stored in the attributes of the class. The accuracy level is mapped to a set of parameters that specify the overall accuracy and computation cost of the calculation: by increasing the value from 1 to 3, we get larger simulation boxes, longer simulation times, smaller time steps and more configuration samples.

Once the required input information is retrieved and the relevant parameters are set, we can start with the simulation workflow. For that, the function also contains the whole simulation workflow that has been already described in section 2). This CobrammSimulationEngine class does not contain the code that executes the individual operations of the simulation workflow. Instead, it calls the code for the various simulation steps that has been included in the COBRAMM engine.

As an example, let us briefly consider the MM optimization and equilibration step. This part of the syntactic layer makes use of the classes AmberInput and AmberCalculator that are included in COBRAMM and constitute a smart limited-purpose wrapper to Amber MD. Inspecting the import statements at the beginning of simulation_engine.py we have a list of the parts of COBRAMM that are used by this layer:

  • The classes AmberCalculator and AmberInput constitute the COBRAMM internal wrapper to Amber.

  • The classes CobrammCalculator and CobrammInput constitute a wrapper to COBRAMM, available in the same COBRAMM code.

  • The class HarmonicSampling contains the Wigner sampling code.

After the CobrammSimulationEngine.run method has been run, an attribute flag CobrammSimulationEngine.executed is set to True and the spectrum computed with the simulation workflow becomes available for the interoperability layer.

Tests#

If you wish to verify that the wrapper is working as expected, you can run its test suite. Install the wrapper first and, after the installation:

  1. Go inside the tests folder cd tests

  2. Execute the command python -m unittest

This will run all tests in the test suite, and it will take approximately 1 hour to run them all. If you prefer you can just run one of them by specifying the name of the file.

python -m unittest test_engine.py

The suite is composed of three different tests

  • test_end_to_end: It is intended to test the end to end interaction between application, wrapper and the simulation engine.

  • test_session: It comprises both integration tests related to the interaction with the simulation engine and unit tests of the methods that are part of the SimPhoNy wrapper API.

  • test_engine: This test suite contains unit tests for the simulation engine.