Development
Contents
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
andCobrammSimulationEngine.spectrum
: list to store the linear absorption spectrum.
These attributes are set and deleted with appropriate methods (lines 56-71).
56def add_atom(self, uid, sym, position):
57"""Add or update atom with a given unique identifier,
58specifying atomic symbol and position (cartesian coordinates)"""
59self.atoms[uid] = [sym, position]
6061
def delete_atom(self, uid):
62"""Delete an atom given its unique identifier"""
63del self.atoms[uid]
6465
def add_property(self, label, value):
66"""Add or update an entry to the input_setup dictionary"""
67self.input_setup[label] = value
6869
def delete_property(self, label):
70"""Delete an entry of input_setup using its unique label"""
71del 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
andAmberInput
constitute the COBRAMM internal wrapper to Amber.The classes
CobrammCalculator
andCobrammInput
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:
Go inside the tests folder
cd tests
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.