ST4SD Examples

This repository contains notebooks illustrating how to use ST4SD APIs to launch, query, and retrieve experiment results.

Quick links

• Available notebooks
• Requirements
• Running via CLI
• Running via a container
• Help and Support
• Contributing
• License

Available notebooks

In the notebooks folder you will find:

• ST4SD Runtime API Example
  • Illustrates the Runtime APIs used for launching, monitoring and retrieve high level results
• ST4SD Datastore - Common Query Examples
  • Illustrates the Datastore APIs used for more intricate querying and arbitrary information retrieval
• ST4SD Runtime API Property Retrieval
  • Illustrates ways to retrieve properties measured by the experiments
• bite-size examples for using python wrappers to the ST4DS REST-APIs

Requirements

These notebooks require st4sd-runtime-core to be installed.

You can follow the instructions in the st4sd-runtime-core repository to install it locally with Jupyter support and proceed to running via CLI, or skip to running via a container to use a pre-built container image.

NOTE: ST4SD requires authentication to be used and the notebooks will guide you on how to do it. To limit the chances of the tokens being stored in the notebook and pushed somewhere we make use of the Password IPython widget. Visual Studio Code, however, currently does not seem to allow pasting in the rendered Password input. If you want to use VSCode, paste your token in the cell that follows it, but make sure to remove it before pushing or sharing your notebooks!

Running via CLI

NOTE: Ensure that if you installed st4sd-runtime-core into a virtual environment, it is activated.

1. Clone the repository locally using

git clone https://github.com/st4sd/st4sd-examples.git

Or, if you prefer to use SSH cloning:

git clone git@github.com:st4sd/st4sd-examples.git

2. Change into the directory you just cloned

cd st4sd-examples

3. Start the Jupyter notebook (in this example "ST4SD Runtime API Example.ipynb")

jupyter-notebook "notebooks/ST4SD Runtime API Example.ipynb"

Running via a container

1. Clone the repository locally using

git clone https://github.com/st4sd/st4sd-examples.git

Or, if you prefer to use SSH cloning:

git clone git@github.com:st4sd/st4sd-examples.git

2. Change into the directory you just cloned

cd st4sd-examples

3. Pull the st4sd-runtime-core container image

docker pull quay.io/st4sd/official-base/st4sd-runtime-core

4. Start the container

NOTE: the following command assumes that port 8888 is free.

docker run -w /st4sd-examples --rm -it -v $PWD:/st4sd-examples -p 8888:8888 quay.io/st4sd/official-base/st4sd-runtime-core jupyter notebook --ip 0.0.0.0 --no-browser --allow-root

You can now find the notebooks at one of the addresses that are printed out by the container (use the token provided at the end of the string to authenticate).

Help and Support

Please feel free to reach out to one of the maintainers listed in the MAINTAINERS.md page.

Contributing

We always welcome external contributions. Please see our guidance for details on how to do so.

References

If you use ST4SD in your projects, please consider citing the following:

@software{st4sd_2022,
author = {Johnston, Michael A. and Vassiliadis, Vassilis and Pomponio, Alessandro and Pyzer-Knapp, Edward},
license = {Apache-2.0},
month = {12},
title = {{Simulation Toolkit for Scientific Discovery}},
url = {https://github.com/st4sd/st4sd-runtime-core},
year = {2022}
}

License

This project is licensed under the Apache 2.0 license. Please see details here.