Incorporating a new WaNo

Scientific studies are often obtained by chaining the preparation and execution of multiple interoperable packages one after the other. The scientific process requires the reproducibility of this simulation chain and the reproducibility of the singular modules. Here we show how to incorporate a new WaNo within in SimStack framework, including its Graphical User Interface (GUI), parameters, and execution process.

1. WaNo concept

The Workflow Active Nodes WaNo is specified in an XML file, which SimStack interprets and uses to render the information of the node from the local machine to the HPC resources. It eases the adjustment of input parameters and files and is displayed on the right side of the client window, as shown in the last figure of the Installation section. In the code lines below, we highlight in yellow the five possible fields. The absence of the first one will not raise any execution error, but the remaining are mandatory for any implemented WaNo.

<WaNoTemplate>
   <WaNoMeta>
      <Author>
        <Name> Celso R. C. Rego </Name>
        <Email>celsorego@kit.edu</Email>
      </Author>

      <Description>
        This WaNo performs ...
      </Description>

      <Keyword>Some nice words</Keyword>
   </WaNoMeta>

   <WaNoRoot name="TemplateWaNo">
       Load the input files from a given folder
       Define a set of parameters
   </WaNoRoot>

   <WaNoExecCommand>
       Run the simulation
   </WaNoExecCommand>

   <WaNoInputFiles>
       Name of the mandatory files, e.g., scripts.
   </WaNoInputFiles>

   <WaNoOutputFiles>
       Define the expected output files
   </WaNoOutputFiles>
</WaNoTemplate>

Every element is required to have a name attribute. This name cannot contain “.” characters. Below we give an overview of the meaning for each element inside the WaNoTemplate in the XML file above.

• WaNoMeta This field is dedicated to the developer information and describes the aims of the WaNo.

• WaNoRoot Here is where we define the set of parameters to be exposed and the inputs files of the simulation.

• WaNoExecCommand This part is a multiline string, which contains the script or program to execute, when the WaNo starts.

• WaNoInputFiles This segment is where we name all static input files, which have to be present in the WaNo folder.

• WaNoOutputFiles Here is where we name all the expected output files in the output directory. If not present, your WaNo will be shown as aborted (red folder).

2. Morse potential example

In this example, we want to include a python program in a new WaNo. This script computes the Morse potential \(V(r)=D_{e}[1-e^{-a(r-r_{e})}]^2-D_{e}\) energy of a particular diatomic molecule as a function of the intermolecular distance \((r-r_{e})\) using Numpy. Here De is the well depth energy relative to the atoms apart from each other. a controls the width of the potential, \(\color{green}{r_{e}}\) gives the minimum potential distance. This scrip loads .yml file from where it reads the inputs to compute the Morse potential energy. Via the command line, it is executed as follows:

python/intepretor morse.py

2.1 Starting a new WaNo project

At this point, we want to move from the code line above to a SimStack GUI. To incorporate a new tool, first, we create a new directory with the WaNo name (see the code lines below) in the WaNo repository directory, see Paths configuration in Simstack Server Configuration section. The WaNo name should be unique. In our example, we name it as MORSE-pot.

mkdir Morse-Pot
cd Morse-pot

Next, we create a Morse-pot.xml file, and this will specify the GUI elements in this WaNo. To give our new WaNo an icon image, we may add an image Morse-pot.png directly in the WaNo folder. In such a way, the SimStack client will automatically load this image on the node’s area. Now, we have to consider what aspect in this simulation project we want to emphasize, which parameters should be fixed, which are adjustable. For this particular case, we make all Morse potential parameters flexible. Still, we think of Density Functional Theory, Molecular Dynamics, or Continues model codes, where we have many parameters, which in principle, we are allowed to change. In a scenario of codes with a considerable number of parameters, exposing all of them in most cases is unnecessary and not recommended. In this situation, we should focus only on the most relevant ones for the problems we want to simulate.

The python script here named morse.py accepts arguments to define the Morse potential shape and specify inter-molecular distance. The outputs are written in the MOROUT.yml file. For more details, see the code lines below.

import numpy as np
import sys, os, yaml

def Vmorse(r,De, a, re):
    """Calculate the Morse potential, V(r).
    """
    return De * (1.0 - np.exp(-a*(r - re)))**2.0 - De


if __name__ == '__main__':
    
    with open('rendered_wano.yml') as file:
        wano_file = yaml.full_load(file)

    decimal_points = 6 # decimal points

    De = wano_file["De (Ry)"] #0.48 #Ry
    a =  wano_file["a"] #1.8 
    re = wano_file["re (A)"] #0.8 #Angs
    r = wano_file["Mol_distance (A)"]  #0.4 #Angs
    
    # get morse potential energy
    ymorse = Vmorse(r, De, a, re)

    MOROUT = wano_file  # output file
    
    MOROUT["energy"] = float(round(ymorse,decimal_points))
    try:   
        with open("MOROUT.yml",'w') as out:
            yaml.dump(MOROUT, out,default_flow_style=False)
    except IOError:
        print("I/O error")

To get this .py file up running and take advantage of the GUI with the chosen parameters highlighted in yellow below, we must put the script inside the WaNoInputFile tag, lines 31-33.

<WaNoTemplate>
    
    <WaNoMeta>
 		<Author>
  			<Name> Celso R. C. Rego </Name>
  			<Email>celsorego@kit.edu</Email>
 		</Author>

		<Description>
   			This WaNo perform a plot of Morse potential for H2 molecule.
 		</Description>

 		<Keyword>Morse-pot</Keyword>
	</WaNoMeta>
	
	<WaNoRoot name="MORSE-pot">

	<WaNoFloat name="De (Ry)" description = "The well depth (defined relative to the dissociated atoms)">0.48</WaNoFloat>
	<WaNoFloat name="a" description = "Controls the width of the potential (the smaller a is, the larger the well)" >1.8</WaNoFloat>
	<WaNoFloat name="re (A)" description = "The equilibrium bond distance">0.8</WaNoFloat>
	<WaNoFloat name="Mol_distance (A)" description = "Distance between the atoms" >1.0</WaNoFloat>
	
	</WaNoRoot>
	
	<WaNoExecCommand>
		export NANOVER=V4
		source $NANOMATCH/$NANOVER/configs/simstack_kit.config
		python morse.py
	</WaNoExecCommand>
	
	<WaNoInputFiles>
		<WaNoInputFile logical_filename="morse.py">morse.py</WaNoInputFile>
	</WaNoInputFiles>

	<WaNoOutputFiles>
		<WaNoOutputFile>MOROUT.yml</WaNoOutputFile>
	</WaNoOutputFiles>
</WaNoTemplate>

Fig 1 The arrows show the correspondence between the exposed parameter set in the GUI with the .xml tags.

• The logical_filename property in line 32 maps out the input file into the file name when transferred to the SimStack server.

• As mentioned above, MOROUT.yml is the expected output file of the script, and in the .xml files, it is managed by lines 35-37

• Regarding the adjustable parameters, we add them inside the WaNoRoot tag as shown in Fig 1 and highlighted in the .py file.

• These parameters basically set up the shape of the Morse potential. Every parameter comes with its description.