Write experiments

For your first virtual experiment, we will start with a Python script and use a virtual environment where st4sd-runtime-core is installed. This is a great way to quickly prototype virtual experiments without worrying about making them shareable with others. Check out Using containers for shareable virtual experiments for an example.

Begin by creating the directory /tmp/hello-world and navigating into it. We are going to store all files relevant to the virtual experiment of this example in this directory.

A good way to become familiar with ST4SD is to wrap a simple python script in a virtual experiment and execute it. So, let’s build a hello world experiment using python. Create the file printer.py with the following contents:

This Python script is straightforward and does not rely on any external Python packages. If it did, you would need to install the required dependencies using pip install within the virtual environment where st4sd-runtime-core is installed. Since this script has no external dependencies, no additional Python modules need to be installed.

To create a ST4SD virtual experiment based on this script, we will define it using a YAML file. The structure of a ST4SD virtual experiment definition is as follows:

Developers build experiments by connecting together Components and Workflows and identifying the entry point of the virtual experiment.

Components represent individual tasks, while Workflows represent pipelines (i.e. graphs) of Workflows and Components. The example provided demonstrates the execution of a single task. A helpful way to understand virtual experiments is to think of them as programs written in a programming language. In this analogy, Workflows and Components serve as functions, and the entrypoint is similar to declaring a main() function, specifying which function to execute and what arguments to pass to it.

Let’s put together a simple experiment consisting of a single step that prints a message to its standard output.

Place the following in the file hello-world.yaml:

In this example, the entrypoint to the experiment is an instance of the printer component which sets its message parameter to the value “Hello world”.

Moving on to the Components template section we observe that there is a single template called printer. The printer component template has a single parameter called message, which does not have a default value. Instances of this template, run the executable python, passing the absolute path to the printer.py script and the message value as arguments. In the next example we will show you a better way to package experiments alleviating the need to use absolute paths for your scripts.

Let’s run the experiment using elaunch.py. Run the following command from inside the /tmp/hello-world directory

After a few seconds you should see:

The experiment will create the directory hello-world.instance and store all files it generated in it.

If you encountered any issues during the process, please refer to the troubleshooting section of the documentation for guidance on launching experiments locally.

Now that you have ran the experiment, take a moment to explore its outputs. You can find the output files following directory: hello-world.instance/stages/stage0/entry-instance.

In ST4SD you can override the parameters of entry-instance that the entrypoint sets via the dictionary entrypoint.execute[0].args.

For example, place the following into a new file my-variables.yaml:

Then remove the hello-world.instance directory and run the experiment again but this time use load the my-variables.yaml file:

The stdout of the hello component can be found in the following file: hello-world.instance/stages/stage0/entry-instance/out.stdout.

When automating simulation codes with custom bash scripts, you may have experienced difficulties with absolute paths when relocating your codes to different directories or execution environments. ST4SD provides a solution to this issue. It offers two methods for packaging multiple files, with the most convenient approach being the use of the Standard project structure. This structure consists of a virtual experiment definition, defined in a YAML file, and an optional manifest file, which specifies additional directories to be included with the virtual experiment. The manifest file has the following format:

The manifest file has the following format:

This instructs the runtime system to create a directory called destinationDirectoryName using the files from the path sourceDirectory. If the sourceDirectory is not an absolute path then it is considered relative to the location of the experiment definition YAML file.

To convert the above example to use the Standard project structure, first create the directory /tmp/hello-world/bin and move the printer.py script into it. Next, create the file manifest.yaml under the directory /tmp/hello-world/ with the following content:

Now, let’s update the virtual definition to use the bin/printer.py file. You just need to change the last line in the components section of your hello-world.yaml file:

Replace the absolute path /tmp/hello-world/printer.py with bin/printer.py:ref. The :ref suffix indicates that this is a reference to a file, rather than a direct path. At runtime, the system will use the manifest.yaml file to resolve this reference, enabling you to include additional files with your virtual experiment definition in a flexible and portable way.

Your updated hello-world.yaml file should now look like this:

You should end up with the following files:

Finally, let’s run this experiment:

After a few seconds you should see this output on your terminal:

Congratulations! You have successfully packaged your virtual experiment!

Modify your printer.py script to import a Python package, such as transformers. To ensure successful execution, make sure to install transformers within the same virtual environment where st4sd-runtime-core is installed.

Next, run it elaunch.py:

Double check that it runs to completion.

To make experiments truly shareable, they must include the following key information:

In the above example we wrapped a single-step executable into a virtual experiment, covering the second and third requirements for a single-step experiment. In this example, we will utilize a container to share the software dependencies of the printer.py python script, addressing the first requirement.

Create a new directory in /tmp/docker-package and cd into it, we will use it for the files of this virtual experiment.

In a requirements.txt file place the python dependencies of your script. The printer.py python script that we use here does not have any python requirements but we’ll just install transformers in the container we use to execute the script just to demonstrate the method:

The contents of the requirements.txt file are:

Next, create a file called Dockerfile with the following contexts:

Make sure you have the following files in the directory you are currently in:

To build your container, run docker build:

If you plan to share your experiment with others, you will need to push your containers to a remote container registry, such as Docker Hub. This allows others to easily access and pull your container images, making it simpler to share and reproduce your experiment.

To push your container to a remote registry, you can use the following steps:

For example:

Create the file docker-package.yaml in the /tmp/docker-package directory with the following contents:

The differences between this experiment and above hello-world.yaml experiment are all about the printer component:

The resulting file tree in /tmp/docker-package should be:

Run your virtual experiment using elaunch.py:

If you encountered any issues during the process, please refer to the troubleshooting section of the documentation for guidance on launching experiments locally.

Now that you have ran the experiment, take a moment to explore its outputs. You can find the output files following directory: docker-package.instance/stages/stage0/entry-instance.

In this example, we will create a virtual experiment that performs the Parameterized Model 3 (PM3) method in GAMESS US. PM3 is a semi-empirical quantum chemistry method. Scientists use it to calculate the molecular properties and energies when computational efficiency is a priority as an alternative to high accuracy but slow to run high-level quantum methods like Hartree-Fock or Density Functional Theory (DFT).

Start by creating a new directory in /tmp/gamess-us-pm3 containing 2 directories: bin and hooks like so:

Create the file bin/run-gamess.sh using the following:

Then download the extract_gmsout.py script and store it in the bin directory.

Next, make the run-gamess.sh script executable by running chmod +x bin/run-gamess.sh from inside the /tmp/gamess-us-pm3 directory.

Download the RestartHook example and save it under hooks/semi_empirical_restart.py. This script checks if the PM3 method in GAMESS US has converged. If not, it triggers a task restart. You can find more information on RestartHooks in our documentation about restarting tasks.

Next, prepare the definition of the experiment by pasting the following into the gamess-us-pm3.yaml file:

Finally create your manifest.yaml file:

You should now have the following file structure:

Try starting your experiment now using a container runtime.

Create your GAMESS-US input molecule.inp file in the directory /tmp/gamess-us-pm3. You can use this example input file:

You should now have this structure:

Launch your experiment providing the input file molecule.inp and the manifest file manifest.yaml.

After a couple of minutes you should see:

The gamess-us-pm3.instance directory will have the following structure:

Examine the files under stages/stage0/optimise and stages/stage0/parse-gamess.

These were the contents of stages/stage0/parse-gamess/energies.csv for the experiment we ran on our laptop: