This repository contains notebooks illustrating how to use ST4SD APIs to launch, query, and retrieve experiment results.
- Available notebooks
- Requirements
- Running via CLI
- Running via a container
- Help and Support
- Contributing
- License
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
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!
NOTE: Ensure that if you installed st4sd-runtime-core
into a virtual environment, it is activated.
- Clone the repository locally using
git clone https://github.com/st4sd/st4sd-examples.git
Or, if you prefer to use SSH cloning:
git clone [email protected]:st4sd/st4sd-examples.git
- Change into the directory you just cloned
cd st4sd-examples
- Start the Jupyter notebook (in this example "ST4SD Runtime API Example.ipynb")
jupyter-notebook "notebooks/ST4SD Runtime API Example.ipynb"
- Clone the repository locally using
git clone https://github.com/st4sd/st4sd-examples.git
Or, if you prefer to use SSH cloning:
git clone [email protected]:st4sd/st4sd-examples.git
- Change into the directory you just cloned
cd st4sd-examples
- Pull the
st4sd-runtime-core
container image
docker pull quay.io/st4sd/official-base/st4sd-runtime-core
- 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).
Please feel free to reach out to one of the maintainers listed in the MAINTAINERS.md page.
We always welcome external contributions. Please see our guidance for details on how to do so.
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}
}
This project is licensed under the Apache 2.0 license. Please see details here.