<div align="center">
<a href="https://github.com/CrayLabs/SmartSim"><img src="https://raw.githubusercontent.com/CrayLabs/SmartSim/master/doc/images/SmartSim_Large.png" width="90%"><img></a>
<br />
<br />
<div display="inline-block">
<a href="https://github.com/CrayLabs/SmartSim"><b>Home</b></a>
<a href="https://www.craylabs.org/docs/installation_instructions/basic.html"><b>Install</b></a>
<a href="https://www.craylabs.org/docs/overview.html"><b>Documentation</b></a>
<a href="https://github.com/CrayLabs"><b>Cray Labs</b></a>
<a href="mailto:craylabs@hpe.com"><b>Contact</b></a>
<a href="https://join.slack.com/t/craylabs/shared_invite/zt-nw3ag5z5-5PS4tIXBfufu1bIvvr71UA"><b>Join us on Slack!</b></a>
</div>
<br />
<br />
</div>
<div align="center">
[](https://github.com/CrayLabs/SmartSim/blob/master/LICENSE.md)
[](https://github.com/psf/black)
[](https://codecov.io/gh/CrayLabs/SmartSim)
[](https://pepy.tech/project/smartsim)
</div>
------------
# SmartSim
SmartSim is made up of two parts
1. SmartSim Infrastructure Library (This repository)
2. [SmartRedis](https://github.com/CrayLabs/SmartRedis)
The two library components are designed to work together, but can also be used
independently.
*SmartSim* is a workflow library that makes it easier to use common Machine Learning (ML)
libraries, like PyTorch and TensorFlow, in High Performance Computing (HPC) simulations
and applications. SmartSim launches ML infrastructure on HPC systems alongside user
workloads.
*SmartRedis* provides an API to connect HPC workloads, particularly (MPI + X) simulations,
to the ML infrastructure, namely the The [Orchestrator database](https://www.craylabs.org/docs/orchestrator.html),
launched by SmartSim.
Applications integrated with the SmartRedis clients, written in Fortran, C, C++ and Python,
can send data to and remotely request SmartSim infrastructure to execute ML models and scripts
on GPU or CPU. The distributed Client-Server paradigm allows for data to be seamlessly
exchanged between applications at runtime without the utilization of MPI.
----------
**Table of Contents**
- [SmartSim](#smartsim)
- [Quick Start](#quick-start)
- [SmartSim Infrastructure Library](#smartsim-infrastructure-library)
- [Experiments](#experiments)
- [Hello World](#hello-world)
- [Hello World MPI](#hello-world-mpi)
- [Experiments on HPC Systems](#experiments-on-hpc-systems)
- [Interactive Launch Example](#interactive-launch-example)
- [Batch Launch Examples](#batch-launch-examples)
- [Infrastructure Library Applications](#infrastructure-library-applications)
- [Redis + RedisAI](#redis--redisai)
- [Local Launch](#local-launch)
- [Interactive Launch](#interactive-launch)
- [Batch Launch](#batch-launch)
- [SmartRedis](#smartredis)
- [Tensors](#tensors)
- [Datasets](#datasets)
- [SmartSim + SmartRedis Tutorials](#smartsim--smartredis-tutorials)
- [Run the Tutorials](#run-the-tutorials)
- [Online Analysis](#online-analysis)
- [Lattice Boltzmann Simulation](#lattice-boltzmann-simulation)
- [Online Processing](#online-processing)
- [Singular Value Decomposition](#singular-value-decomposition)
- [Online Inference](#online-inference)
- [PyTorch CNN Example](#pytorch-cnn-example)
- [Publications](#publications)
- [Cite](#cite)
- [bibtex](#bibtex)
----
# Quick Start
The documentation has a number of tutorials that make it easy to get used to SmartSim locally
before using it on your system. Each tutorial is a Jupyter notebook that can be run through the
[SmartSim Tutorials docker image](https://github.com/orgs/CrayLabs/packages?repo_name=SmartSim)
which will run a jupyter lab with the tutorials, SmartSim, and SmartRedis installed.
```bash
docker pull ghcr.io/craylabs/smartsim-tutorials:latest
docker run -p 8888:8888 ghcr.io/craylabs/smartsim-tutorials:latest
# click on link to open jupyter lab
```
# SmartSim Infrastructure Library
The Infrastructure Library (IL), the ``smartsim`` python package,
facilitates the launch of Machine Learning and simulation
workflows. The Python interface of the IL creates, configures, launches and monitors
applications.
## Experiments
The [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment) object
is the main interface of SmartSim. Through the [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment)
users can create references to user applications called ``Models``.
### Hello World
Below is a simple example of a workflow that uses the IL to launch hello world
program using the local launcher which is designed for laptops and single nodes.
```python
from smartsim import Experiment
exp = Experiment("simple", launcher="local")
settings = exp.create_run_settings("echo", exe_args="Hello World")
model = exp.create_model("hello_world", settings)
exp.start(model, block=True)
print(exp.get_status(model))
```
### Hello World MPI
The [Experiment.create_run_settings](https://www.craylabs.org/docs/api/smartsim_api.html#smartsim.experiment.Experiment.create_run_settings) method returns a ``RunSettings`` object which
defines how a model is launched. There are many types of ``RunSettings`` [supported by
SmartSim](https://www.craylabs.org/docs/api/smartsim_api.html#settings).
- ``RunSettings``
- ``MpirunSettings``
- ``SrunSettings``
- ``AprunSettings``
- ``JsrunSettings``
The following example launches a hello world MPI program using the local launcher
for single compute node, workstations and laptops.
```Python
from smartsim import Experiment
exp = Experiment("hello_world", launcher="local")
mpi_settings = exp.create_run_settings(exe="echo",
exe_args="Hello World!",
run_command="mpirun")
mpi_settings.set_tasks(4)
mpi_model = exp.create_model("hello_world", mpi_settings)
exp.start(mpi_model, block=True)
print(exp.get_status(model))
```
If an argument of `run_command="auto"` (the default) is passed to
`Experiment.create_run_settings`, SmartSim will attempt to find a run command on the
system with which it has a corresponding `RunSettings` class. If one can be found,
`Experiment.create_run_settings` will instance and return an object of that type.
-----------
## Experiments on HPC Systems
SmartSim integrates with common HPC schedulers providing batch and interactive
launch capabilities for all applications:
- Slurm
- LSF
- PBSPro
- Local (for laptops/single node, no batch)
In addition, on Slurm and PBS systems, [Dragon](https://dragonhpc.github.io/dragon/doc/_build/html/index.html)
can be used as a launcher. Please refer to the documentation for instructions on
how to insall it on your system and use it in SmartSim.
### Interactive Launch Example
The following launches the same ``hello_world`` model in an interactive allocation.
```bash
# get interactive allocation (Slurm)
salloc -N 3 --ntasks-per-node=20 --ntasks 60 --exclusive -t 00:10:00
# get interactive allocation (PBS)
qsub -l select=3:ncpus=20 -l walltime=00:10:00 -l place=scatter -I -q <queue>
# get interactive allocation (LSF)
bsub -Is -W 00:10 -nnodes 3 -P <project> $SHELL
```
This same script will run on a SLURM, PBS, or LSF system as the ``launcher``
is set to `auto` in the [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment)
initialization. The run command like ``mpirun``,
``aprun`` or ``srun`` will be automatically detected from what is available on the
system.
```python
# hello_world.py
from smartsim import Experiment
exp = Experiment("hello_world_exp", launcher="auto")
run = exp.create_run_settings(exe="echo", exe_args="Hello World!")
run.set_tasks(60)
run.set_tasks_per_node(20)
model = exp.create_model("hello_world", run)
exp.start(model, block=True, summary=True)
print(exp.get_status(model))
```
```bash
# in interactive terminal
python hello_world.py
```
This script could also be launched in a batch file instead of an
interactive terminal. For example, for Slurm:
```bash
#!/bin/bash
#SBATCH --exclusive
#SBATCH --nodes=3
#SBATCH --ntasks-per-node=20
#SBATCH --time=00:10:00
python /path/to/hello_world.py
```
```bash
# on Slurm system
sbatch run_hello_world.sh
```
### Batch Launch Examples
SmartSim can also launch workloads in a batch directly from Python, without the need
for a batch script. Users can launch groups of ``Model`` instances in a ``Ensemble``.
The following launches 4 replicas of the the same ``hello_world`` model.
```python
# hello_ensemble.py
from smartsim import Experiment
exp = Experiment("hello_world_batch", launcher="auto")
# define resources for all ensemble members
batch = exp.create_batch_settings(nodes=4, time="00:10:00", account="12345-Cray")
batch.set_queue("premium")
# define how each member should run
run = exp.create_run_settings(exe="echo", exe_args="Hello World!")
run.set_tasks(60)
run.set_tasks_per_node(20)
ensemble = exp.create_ensemble("hello_world",
batch_settings=batch,
run_settings=run,
replicas=4)
exp.start(ensemble, block=True, summary=True)
print(exp.get_status(ensemble))
```
```bash
python hello_ensemble.py
```
Similar to the interactive example, this same script will run on a SLURM, PBS,
or LSF system as the ``launcher`` is set to `auto` in the
[Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment)
initialization. Local launching does not support batch workloads.
--------
# Infrastructure Library Applications
- Orchestrator - In-memory data store and Machine Learning Inference (Redis + RedisAI)
## Redis + RedisAI
The ``Orchestrator`` is an in-memory database that utilizes Redis and RedisAI to provide
a distributed database and access to ML runtimes from Fortran, C, C++ and Python.
SmartSim provides classes that make it simple to launch the database in many
configurations and optionally form a distributed database cluster. The examples
below will show how to launch the database. Later in this document we will show
how to use the database to perform ML inference and processing.
### Local Launch
The following script launches a single database using the local launcher.
[Experiment.create_database](https://www.craylabs.org/docs/api/smartsim_api.html#smartsim.experiment.Experiment.create_database)
will initialize an ``Orchestrator`` instance corresponding to the specified launcher.
```python
# run_db_local.py
from smartsim import Experiment
exp = Experiment("local-db", launcher="local")
db = exp.create_database(port=6780, # database port
interface="lo") # network interface to use
# by default, SmartSim never blocks execution after the database is launched.
exp.start(db)
# launch models, analysis, training, inference sessions, etc
# that communicate with the database using the SmartRedis clients
# stop the database
exp.stop(db)
```
### Interactive Launch
The ``Orchestrator``, like ``Ensemble`` instances, can be launched locally, in interactive
allocations, or in a batch.
The following example launches a distributed (3 node) database cluster
in an interactive allocation.
```bash
# get interactive allocation (Slurm)
salloc -N 3 --ntasks-per-node=1 --exclusive -t 00:10:00
# get interactive allocation (PBS)
qsub -l select=3:ncpus=1 -l walltime=00:10:00 -l place=scatter -I -q queue
# get interactive allocation (LSF)
bsub -Is -W 00:10 -nnodes 3 -P project $SHELL
```
```python
# run_db.py
from smartsim import Experiment
# auto specified to work across launcher types
exp = Experiment("db-on-slurm", launcher="auto")
db_cluster = exp.create_database(db_nodes=3,
db_port=6780,
batch=False,
interface="ipogif0")
exp.start(db_cluster)
print(f"Orchestrator launched on nodes: {db_cluster.hosts}")
# launch models, analysis, training, inference sessions, etc
# that communicate with the database using the SmartRedis clients
exp.stop(db_cluster)
```
```bash
# in interactive terminal
python run_db.py
```
### Batch Launch
The ``Orchestrator`` can also be launched in a batch without the need for an interactive allocation.
SmartSim will create the batch file, submit it to the batch system, and then wait for the database
to be launched. Users can hit CTRL-C to cancel the launch if needed.
```Python
# run_db_batch.py
from smartsim import Experiment
exp = Experiment("batch-db-on-pbs", launcher="auto")
db_cluster = exp.create_database(db_nodes=3,
db_port=6780,
batch=True,
time="00:10:00",
interface="ib0",
account="12345-Cray",
queue="cl40")
exp.start(db_cluster)
print(f"Orchestrator launched on nodes: {db_cluster.hosts}")
# launch models, analysis, training, inference sessions, etc
# that communicate with the database using the SmartRedis clients
exp.stop(db_cluster)
```
```bash
python run_db_batch.py
```
------
# SmartRedis
The SmartSim IL Clients ([SmartRedis](https://github.com/CrayLabs/SmartRedis))
are implementations of Redis clients that implement the RedisAI
API with additions specific to scientific workflows.
SmartRedis clients are available in Fortran, C, C++, and Python.
Users can seamlessly pull and push data from the Orchestrator from different languages.
## Tensors
Tensors are the fundamental data structure for the SmartRedis clients. The Clients
use the native array format of the language. For example, in Python, a tensor is
a NumPy array while the C/C++ clients accept nested and contiguous arrays.
When stored in the database, all tensors are stored in the same format. Hence,
any language can receive a tensor from the database no matter what supported language
the array was sent from. This enables applications in different languages to communicate
numerical data with each other at runtime.
For more information on the tensor data structure, see
[the documentation](https://www.craylabs.org/docs/sr_data_structures.html#tensor)
## Datasets
Datasets are collections of Tensors and associated metadata. The ``Dataset`` class
is a user space object that can be created, added to, sent to, and retrieved from
the Orchestrator.
For an example of how to use the ``Dataset`` class, see the [Online Analysis example](#online-analysis)
For more information on the API, see the
[API documentation](https://www.craylabs.org/docs/sr_data_structures.html#dataset)
# SmartSim + SmartRedis Tutorials
SmartSim and SmartRedis were designed to work together. When launched through
SmartSim, applications using the SmartRedis clients are directly connected to
any Orchestrator launched in the same [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment).
In this way, a SmartSim [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment) becomes a driver for coupled ML and Simulation
workflows. The following are simple examples of how to use SmartSim and SmartRedis
together.
## Run the Tutorials
Each tutorial is a Jupyter notebook that can be run through the
[SmartSim Tutorials docker image](https://github.com/orgs/CrayLabs/packages?repo_name=SmartSim)
which will run a jupyter lab with the tutorials, SmartSim, and SmartRedis installed.
```bash
docker pull ghcr.io/craylabs/smartsim-tutorials:latest
docker run -p 8888:8888 ghcr.io/craylabs/smartsim-tutorials:latest
```
Each of the following examples can be found in the
[SmartSim documentation](https://www.craylabs.org/docs/tutorials/getting_started/getting_started.html).
## Online Analysis
Using SmartSim, HPC applications can be monitored in real time by streaming data
from the application to the database. SmartRedis clients can retrieve the
data, process, analyze it, and finally store any updated data back to the database for
use by other clients.
The following is an example of how a user could monitor and analyze a simulation.
The example here uses the Python client; however, SmartRedis clients are also available
for C, C++, and Fortran. All SmartRedis clients implement the same API.
The example will produce [this visualization](https://user-images.githubusercontent.com/13009163/127622717-2c9e4cfd-50f4-4d94-88c4-8c05fa2fa616.mp4) while the simulation is running.
#### Lattice Boltzmann Simulation
Using a [Lattice Boltzmann Simulation](https://en.wikipedia.org/wiki/Lattice_Boltzmann_methods),
this example demonstrates how to use the SmartRedis ``Dataset`` API to stream
data over the Orchestrator deployed by SmartSim.
The simulation will be composed of two parts: `fv_sim.py` which will generate data from
the Simulation and store it in the Orchestrator, and `driver.py`
which will launch the Orchestrator, start `fv_sim.py` and check for data posted to the
Orchestrator to plot updates in real-time.
The following code highlights the sections of `fv_sim.py` that are responsible for
transmitting the data needed to plot timesteps of the simulation to the Orchestrator.
```Python
# fv_sim.py
from smartredis import Client
import numpy as np
# initialization code omitted
# save cylinder location to database
cylinder = (X - x_res/4)**2 + (Y - y_res/2)**2 < (y_res/4)**2 # bool array
client.put_tensor("cylinder", cylinder.astype(np.int8))
for time_step in range(steps): # simulation loop
for i, cx, cy in zip(idxs, cxs, cys):
F[:,:,i] = np.roll(F[:,:,i], cx, axis=1)
F[:,:,i] = np.roll(F[:,:,i], cy, axis=0)
bndryF = F[cylinder,:]
bndryF = bndryF[:,[0,5,6,7,8,1,2,3,4]]
rho = np.sum(F, 2)
ux = np.sum(F * cxs, 2) / rho
uy = np.sum(F * cys, 2) / rho
Feq = np.zeros(F.shape)
for i, cx, cy, w in zip(idxs, cxs, cys, weights):
Feq[:,:,i] = rho * w * ( 1 + 3*(cx*ux+cy*uy) + 9*(cx*ux+cy*uy)**2/2 - 3*(ux**2+uy**2)/2 )
F += -(1.0/tau) * (F - Feq)
F[cylinder,:] = bndryF
# Create a SmartRedis dataset with vorticity data
dataset = Dataset(f"data_{str(time_step)}")
dataset.add_tensor("ux", ux)
dataset.add_tensor("uy", uy)
# Put Dataset in db at key "data_{time_step}"
client.put_dataset(dataset)
```
The driver script, `driver.py`, launches the Orchestrator database and runs
the simulation in a non-blocking fashion. The driver script then uses the SmartRedis
client to pull the DataSet and plot the vorticity while the simulation is running.
```Python
# driver.py
time_steps, seed = 3000, 42
exp = Experiment("finite_volume_simulation", launcher="local")
db = exp.create_database(port=6780, # database port
interface="lo") # network interface db should listen on
# create the lb simulation Model reference
settings = exp.create_run_settings("python",
exe_args=["fv_sim.py",
f"--seed={seed}",
f"--steps={time_steps}"])
model = exp.create_model("fv_simulation", settings)
model.attach_generator_files(to_copy="fv_sim.py")
exp.generate(db, model, overwrite=True)
exp.start(db)
client = Client(address=db.get_address()[0], cluster=False)
# start simulation (non-blocking)
exp.start(model, block=False, summary=True)
# poll until simulation starts and then retrieve data
client.poll_key("cylinder", 200, 100)
cylinder = client.get_tensor("cylinder").astype(bool)
for i in range(0, time_steps):
client.poll_key(f"data_{str(i)}", 10, 1000)
dataset = client.get_dataset(f"data_{str(i)}")
ux, uy = dataset.get_tensor("ux"), dataset.get_tensor("uy")
# analysis/plotting code omitted
exp.stop(db)
```
For more examples of how to use SmartSim and SmartRedis together to perform
online analysis, please see the
[online analsysis tutorial section](https://www.craylabs.org/docs/tutorials/online_analysis/lattice/online_analysis.html) of the
SmartSim documentation.
## Online Processing
Each of the SmartRedis clients can be used to remotely execute
[TorchScript](https://pytorch.org/docs/stable/jit.html) code on data
stored within the database. The scripts/functions are executed in the Torch
runtime linked into the database.
Any of the functions available in the
[TorchScript builtins](https://pytorch.org/docs/stable/jit_builtin_functions.html#builtin-functions)
can be saved as "script" or "functions" in the database and used directly by
any of the SmartRedis Clients.
### Singular Value Decomposition
For example, the following code sends the built-in
[Singular Value Decomposition](https://pytorch.org/docs/stable/generated/torch.svd.html)
to the database and execute it on a dummy tensor.
```python
import numpy as np
from smartredis import Client
# don't even need to import torch
def calc_svd(input_tensor):
return input_tensor.svd()
# connect a client to the database
client = Client(cluster=False)
# get dummy data
tensor = np.random.randint(0, 100, size=(5, 3, 2)).astype(np.float32)
client.put_tensor("input", tensor)
client.set_function("svd", calc_svd)
client.run_script("svd", "calc_svd", "input", ["U", "S", "V"])
# results are not retrieved immediately in case they need
# to be fed to another function/model
U = client.get_tensor("U")
S = client.get_tensor("S")
V = client.get_tensor("V")
print(f"U: {U}, S: {S}, V: {V}")
```
The processing capabilities make it simple to form computational pipelines of
functions, scripts, and models.
See the full [TorchScript Language Reference](https://pytorch.org/docs/stable/jit.html#torchscript-language)
documentation for more information on available methods, functions, and how
to create your own.
## Online Inference
SmartSim supports the following frameworks for querying Machine Learning models
from C, C++, Fortran and Python with the SmartRedis Clients:
<table>
<thead>
<tr>
<th style="text-align:center">RedisAI Version</th>
<th style="text-align:center">Libraries</th>
<th style="text-align:center">Supported Version</th>
</tr>
</thead>
<tbody style="text-align:center">
<tr>
<td rowspan="3">1.2.7</td>
<td>PyTorch</td>
<td>2.1.0</td>
</tr>
<tr>
<td>TensorFlow\Keras</td>
<td>2.15.0</td>
</tr>
<tr>
<td>ONNX</td>
<td>1.14.1</td>
</tr>
</tbody>
</table>
A [number of other libraries](https://github.com/onnx/onnxmltools) are
supported through ONNX, like [SciKit-Learn](https://github.com/onnx/sklearn-onnx/)
and [XGBoost](https://github.com/onnx/onnxmltools/tree/master/tests/xgboost).
**Note:** It's important to remember that SmartSim utilizes a client-server model. To run
experiments that utilize the above frameworks, you must first start the Orchestrator
database with SmartSim.
### PyTorch CNN Example
The example below shows how to spin up a database with SmartSim and
invoke a PyTorch CNN model using the SmartRedis clients.
```python
# simple_torch_inference.py
import io
import torch
import torch.nn as nn
from smartredis import Client
from smartsim import Experiment
exp = Experiment("simple-online-inference", launcher="local")
db = exp.create_database(port=6780, interface="lo")
class Net(nn.Module):
def __init__(self):
super().__init__()
self.conv = nn.Conv2d(1, 1, 3)
def forward(self, x):
return self.conv(x)
torch_model = Net()
example_forward_input = torch.rand(1, 1, 3, 3)
module = torch.jit.trace(torch_model, example_forward_input)
model_buffer = io.BytesIO()
torch.jit.save(module, model_buffer)
exp.start(db, summary=True)
address = db.get_address()[0]
client = Client(address=address, cluster=False)
client.put_tensor("input", example_forward_input.numpy())
client.set_model("cnn", model_buffer.getvalue(), "TORCH", device="CPU")
client.run_model("cnn", inputs=["input"], outputs=["output"])
output = client.get_tensor("output")
print(f"Prediction: {output}")
exp.stop(db)
```
The above python code can be run like any normal python script:
```bash
python simple_torch_inference.py
```
For more examples of how to use SmartSim and SmartRedis together to perform
online inference, please see the
[online inference tutorials section](https://www.craylabs.org/docs/tutorials/ml_inference/Inference-in-SmartSim.html) of the
SmartSim documentation.
--------
# Publications
The following are public presentations or publications using SmartSim
- [Collaboration with NCAR - CGD Seminar](https://www.youtube.com/watch?v=2e-5j427AS0)
- [SmartSim: Using Machine Learning in HPC Simulations](https://arxiv.org/abs/2104.09355)
- [SmartSim: Online Analytics and Machine Learning for HPC Simulations](https://www.youtube.com/watch?v=JsSgq-fq44w&list=PLuQQBBQFfpgq0OvjKbjcYgTDzDxTqtwua&index=11)
- [PyTorch Ecosystem Day Poster](https://assets.pytorch.org/pted2021/posters/J8.png)
--------
# Cite
Please use the following citation when referencing SmartSim, SmartRedis, or any SmartSim related work:
Partee et al., “Using Machine Learning at Scale in HPC Simulations with SmartSim:
An Application to Ocean Climate Modeling”, Journal of Computational Science, Volume 62, 2022, 101707, ISSN 1877-7503
Available: https://doi.org/10.1016/j.jocs.2022.101707.
## bibtex
```latex
@article{PARTEE2022101707,
title = {Using Machine Learning at scale in numerical simulations with SmartSim: An application to ocean climate modeling},
journal = {Journal of Computational Science},
volume = {62},
pages = {101707},
year = {2022},
issn = {1877-7503},
doi = {https://doi.org/10.1016/j.jocs.2022.101707},
url = {https://www.sciencedirect.com/science/article/pii/S1877750322001065},
author = {Sam Partee and Matthew Ellis and Alessandro Rigazzi and Andrew E. Shao and Scott Bachman and Gustavo Marques and Benjamin Robbins},
keywords = {Deep learning, Numerical simulation, Climate modeling, High performance computing, SmartSim},
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/CrayLabs/SmartSim",
"name": "smartsim",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": null,
"keywords": "scientific, ai, workflow, hpc, analysis",
"author": "CrayLabs, a Hewlett Packard Enterprise OSS Organization",
"author_email": "craylabs@hpe.com",
"download_url": "https://files.pythonhosted.org/packages/ad/8e/ea19f09edc4cc5a544f1185b7b362d28141f9283bd9ab5878777fa300e5a/smartsim-0.8.0.tar.gz",
"platform": null,
"description": "\n\n<div align=\"center\">\n <a href=\"https://github.com/CrayLabs/SmartSim\"><img src=\"https://raw.githubusercontent.com/CrayLabs/SmartSim/master/doc/images/SmartSim_Large.png\" width=\"90%\"><img></a>\n <br />\n <br />\n<div display=\"inline-block\">\n <a href=\"https://github.com/CrayLabs/SmartSim\"><b>Home</b></a> \n <a href=\"https://www.craylabs.org/docs/installation_instructions/basic.html\"><b>Install</b></a> \n <a href=\"https://www.craylabs.org/docs/overview.html\"><b>Documentation</b></a> \n <a href=\"https://github.com/CrayLabs\"><b>Cray Labs</b></a> \n <a href=\"mailto:craylabs@hpe.com\"><b>Contact</b></a> \n <a href=\"https://join.slack.com/t/craylabs/shared_invite/zt-nw3ag5z5-5PS4tIXBfufu1bIvvr71UA\"><b>Join us on Slack!</b></a> \n </div>\n <br />\n <br />\n</div>\n\n\n<div align=\"center\">\n\n[](https://github.com/CrayLabs/SmartSim/blob/master/LICENSE.md)\n\n\n\n\n\n\n[](https://github.com/psf/black)\n[](https://codecov.io/gh/CrayLabs/SmartSim)\n[](https://pepy.tech/project/smartsim)\n\n</div>\n\n------------\n\n# SmartSim\n\nSmartSim is made up of two parts\n 1. SmartSim Infrastructure Library (This repository)\n 2. [SmartRedis](https://github.com/CrayLabs/SmartRedis)\n\nThe two library components are designed to work together, but can also be used\nindependently.\n\n*SmartSim* is a workflow library that makes it easier to use common Machine Learning (ML)\nlibraries, like PyTorch and TensorFlow, in High Performance Computing (HPC) simulations\nand applications. SmartSim launches ML infrastructure on HPC systems alongside user\nworkloads.\n\n*SmartRedis* provides an API to connect HPC workloads, particularly (MPI + X) simulations,\nto the ML infrastructure, namely the The [Orchestrator database](https://www.craylabs.org/docs/orchestrator.html),\nlaunched by SmartSim.\n\nApplications integrated with the SmartRedis clients, written in Fortran, C, C++ and Python,\ncan send data to and remotely request SmartSim infrastructure to execute ML models and scripts\non GPU or CPU. The distributed Client-Server paradigm allows for data to be seamlessly\nexchanged between applications at runtime without the utilization of MPI.\n\n----------\n\n**Table of Contents**\n- [SmartSim](#smartsim)\n- [Quick Start](#quick-start)\n- [SmartSim Infrastructure Library](#smartsim-infrastructure-library)\n - [Experiments](#experiments)\n - [Hello World](#hello-world)\n - [Hello World MPI](#hello-world-mpi)\n - [Experiments on HPC Systems](#experiments-on-hpc-systems)\n - [Interactive Launch Example](#interactive-launch-example)\n - [Batch Launch Examples](#batch-launch-examples)\n- [Infrastructure Library Applications](#infrastructure-library-applications)\n - [Redis + RedisAI](#redis--redisai)\n - [Local Launch](#local-launch)\n - [Interactive Launch](#interactive-launch)\n - [Batch Launch](#batch-launch)\n- [SmartRedis](#smartredis)\n - [Tensors](#tensors)\n - [Datasets](#datasets)\n- [SmartSim + SmartRedis Tutorials](#smartsim--smartredis-tutorials)\n - [Run the Tutorials](#run-the-tutorials)\n - [Online Analysis](#online-analysis)\n - [Lattice Boltzmann Simulation](#lattice-boltzmann-simulation)\n - [Online Processing](#online-processing)\n - [Singular Value Decomposition](#singular-value-decomposition)\n - [Online Inference](#online-inference)\n - [PyTorch CNN Example](#pytorch-cnn-example)\n- [Publications](#publications)\n- [Cite](#cite)\n - [bibtex](#bibtex)\n\n----\n\n# Quick Start\n\n\nThe documentation has a number of tutorials that make it easy to get used to SmartSim locally\nbefore using it on your system. Each tutorial is a Jupyter notebook that can be run through the\n[SmartSim Tutorials docker image](https://github.com/orgs/CrayLabs/packages?repo_name=SmartSim)\nwhich will run a jupyter lab with the tutorials, SmartSim, and SmartRedis installed.\n\n```bash\ndocker pull ghcr.io/craylabs/smartsim-tutorials:latest\ndocker run -p 8888:8888 ghcr.io/craylabs/smartsim-tutorials:latest\n# click on link to open jupyter lab\n```\n\n# SmartSim Infrastructure Library\n\nThe Infrastructure Library (IL), the ``smartsim`` python package,\nfacilitates the launch of Machine Learning and simulation\nworkflows. The Python interface of the IL creates, configures, launches and monitors\napplications.\n\n## Experiments\n\nThe [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment) object\nis the main interface of SmartSim. Through the [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment)\nusers can create references to user applications called ``Models``.\n### Hello World\n\nBelow is a simple example of a workflow that uses the IL to launch hello world\nprogram using the local launcher which is designed for laptops and single nodes.\n\n```python\nfrom smartsim import Experiment\n\nexp = Experiment(\"simple\", launcher=\"local\")\n\nsettings = exp.create_run_settings(\"echo\", exe_args=\"Hello World\")\nmodel = exp.create_model(\"hello_world\", settings)\n\nexp.start(model, block=True)\nprint(exp.get_status(model))\n```\n\n### Hello World MPI\n\nThe [Experiment.create_run_settings](https://www.craylabs.org/docs/api/smartsim_api.html#smartsim.experiment.Experiment.create_run_settings) method returns a ``RunSettings`` object which\ndefines how a model is launched. There are many types of ``RunSettings`` [supported by\nSmartSim](https://www.craylabs.org/docs/api/smartsim_api.html#settings).\n\n - ``RunSettings``\n - ``MpirunSettings``\n - ``SrunSettings``\n - ``AprunSettings``\n - ``JsrunSettings``\n\nThe following example launches a hello world MPI program using the local launcher\nfor single compute node, workstations and laptops.\n\n```Python\nfrom smartsim import Experiment\n\nexp = Experiment(\"hello_world\", launcher=\"local\")\nmpi_settings = exp.create_run_settings(exe=\"echo\",\n exe_args=\"Hello World!\",\n run_command=\"mpirun\")\nmpi_settings.set_tasks(4)\n\nmpi_model = exp.create_model(\"hello_world\", mpi_settings)\n\nexp.start(mpi_model, block=True)\nprint(exp.get_status(model))\n```\n\nIf an argument of `run_command=\"auto\"` (the default) is passed to\n`Experiment.create_run_settings`, SmartSim will attempt to find a run command on the\nsystem with which it has a corresponding `RunSettings` class. If one can be found,\n`Experiment.create_run_settings` will instance and return an object of that type.\n\n\n-----------\n## Experiments on HPC Systems\n\nSmartSim integrates with common HPC schedulers providing batch and interactive\nlaunch capabilities for all applications:\n\n - Slurm\n - LSF\n - PBSPro\n - Local (for laptops/single node, no batch)\n\nIn addition, on Slurm and PBS systems, [Dragon](https://dragonhpc.github.io/dragon/doc/_build/html/index.html)\ncan be used as a launcher. Please refer to the documentation for instructions on\nhow to insall it on your system and use it in SmartSim.\n\n\n### Interactive Launch Example\n\nThe following launches the same ``hello_world`` model in an interactive allocation.\n\n```bash\n# get interactive allocation (Slurm)\nsalloc -N 3 --ntasks-per-node=20 --ntasks 60 --exclusive -t 00:10:00\n\n# get interactive allocation (PBS)\nqsub -l select=3:ncpus=20 -l walltime=00:10:00 -l place=scatter -I -q <queue>\n\n# get interactive allocation (LSF)\nbsub -Is -W 00:10 -nnodes 3 -P <project> $SHELL\n```\n\nThis same script will run on a SLURM, PBS, or LSF system as the ``launcher``\nis set to `auto` in the [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment)\ninitialization. The run command like ``mpirun``,\n``aprun`` or ``srun`` will be automatically detected from what is available on the\nsystem.\n\n```python\n# hello_world.py\nfrom smartsim import Experiment\n\nexp = Experiment(\"hello_world_exp\", launcher=\"auto\")\nrun = exp.create_run_settings(exe=\"echo\", exe_args=\"Hello World!\")\nrun.set_tasks(60)\nrun.set_tasks_per_node(20)\n\nmodel = exp.create_model(\"hello_world\", run)\nexp.start(model, block=True, summary=True)\n\nprint(exp.get_status(model))\n```\n```bash\n# in interactive terminal\npython hello_world.py\n```\n\n\nThis script could also be launched in a batch file instead of an\ninteractive terminal. For example, for Slurm:\n\n```bash\n#!/bin/bash\n#SBATCH --exclusive\n#SBATCH --nodes=3\n#SBATCH --ntasks-per-node=20\n#SBATCH --time=00:10:00\n\npython /path/to/hello_world.py\n```\n```bash\n# on Slurm system\nsbatch run_hello_world.sh\n```\n\n\n### Batch Launch Examples\n\nSmartSim can also launch workloads in a batch directly from Python, without the need\nfor a batch script. Users can launch groups of ``Model`` instances in a ``Ensemble``.\n\nThe following launches 4 replicas of the the same ``hello_world`` model.\n\n```python\n# hello_ensemble.py\nfrom smartsim import Experiment\n\nexp = Experiment(\"hello_world_batch\", launcher=\"auto\")\n\n# define resources for all ensemble members\nbatch = exp.create_batch_settings(nodes=4, time=\"00:10:00\", account=\"12345-Cray\")\nbatch.set_queue(\"premium\")\n\n# define how each member should run\nrun = exp.create_run_settings(exe=\"echo\", exe_args=\"Hello World!\")\nrun.set_tasks(60)\nrun.set_tasks_per_node(20)\n\nensemble = exp.create_ensemble(\"hello_world\",\n batch_settings=batch,\n run_settings=run,\n replicas=4)\nexp.start(ensemble, block=True, summary=True)\n\nprint(exp.get_status(ensemble))\n```\n\n```bash\npython hello_ensemble.py\n```\n\nSimilar to the interactive example, this same script will run on a SLURM, PBS,\nor LSF system as the ``launcher`` is set to `auto` in the\n[Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment)\ninitialization. Local launching does not support batch workloads.\n\n\n--------\n\n# Infrastructure Library Applications\n - Orchestrator - In-memory data store and Machine Learning Inference (Redis + RedisAI)\n\n## Redis + RedisAI\n\nThe ``Orchestrator`` is an in-memory database that utilizes Redis and RedisAI to provide\na distributed database and access to ML runtimes from Fortran, C, C++ and Python.\n\nSmartSim provides classes that make it simple to launch the database in many\nconfigurations and optionally form a distributed database cluster. The examples\nbelow will show how to launch the database. Later in this document we will show\nhow to use the database to perform ML inference and processing.\n\n\n### Local Launch\n\nThe following script launches a single database using the local launcher.\n\n[Experiment.create_database](https://www.craylabs.org/docs/api/smartsim_api.html#smartsim.experiment.Experiment.create_database)\nwill initialize an ``Orchestrator`` instance corresponding to the specified launcher.\n\n```python\n# run_db_local.py\nfrom smartsim import Experiment\n\nexp = Experiment(\"local-db\", launcher=\"local\")\ndb = exp.create_database(port=6780, # database port\n interface=\"lo\") # network interface to use\n\n# by default, SmartSim never blocks execution after the database is launched.\nexp.start(db)\n\n# launch models, analysis, training, inference sessions, etc\n# that communicate with the database using the SmartRedis clients\n\n# stop the database\nexp.stop(db)\n```\n\n### Interactive Launch\n\nThe ``Orchestrator``, like ``Ensemble`` instances, can be launched locally, in interactive\nallocations, or in a batch.\n\nThe following example launches a distributed (3 node) database cluster\nin an interactive allocation.\n\n\n```bash\n# get interactive allocation (Slurm)\nsalloc -N 3 --ntasks-per-node=1 --exclusive -t 00:10:00\n\n# get interactive allocation (PBS)\nqsub -l select=3:ncpus=1 -l walltime=00:10:00 -l place=scatter -I -q queue\n\n# get interactive allocation (LSF)\nbsub -Is -W 00:10 -nnodes 3 -P project $SHELL\n\n```\n\n```python\n# run_db.py\nfrom smartsim import Experiment\n\n# auto specified to work across launcher types\nexp = Experiment(\"db-on-slurm\", launcher=\"auto\")\ndb_cluster = exp.create_database(db_nodes=3,\n db_port=6780,\n batch=False,\n interface=\"ipogif0\")\nexp.start(db_cluster)\n\nprint(f\"Orchestrator launched on nodes: {db_cluster.hosts}\")\n# launch models, analysis, training, inference sessions, etc\n# that communicate with the database using the SmartRedis clients\n\nexp.stop(db_cluster)\n```\n```bash\n# in interactive terminal\npython run_db.py\n```\n\n### Batch Launch\n\nThe ``Orchestrator`` can also be launched in a batch without the need for an interactive allocation.\nSmartSim will create the batch file, submit it to the batch system, and then wait for the database\nto be launched. Users can hit CTRL-C to cancel the launch if needed.\n\n```Python\n# run_db_batch.py\nfrom smartsim import Experiment\n\nexp = Experiment(\"batch-db-on-pbs\", launcher=\"auto\")\ndb_cluster = exp.create_database(db_nodes=3,\n db_port=6780,\n batch=True,\n time=\"00:10:00\",\n interface=\"ib0\",\n account=\"12345-Cray\",\n queue=\"cl40\")\n\nexp.start(db_cluster)\n\nprint(f\"Orchestrator launched on nodes: {db_cluster.hosts}\")\n# launch models, analysis, training, inference sessions, etc\n# that communicate with the database using the SmartRedis clients\n\nexp.stop(db_cluster)\n```\n\n```bash\npython run_db_batch.py\n```\n\n------\n# SmartRedis\n\nThe SmartSim IL Clients ([SmartRedis](https://github.com/CrayLabs/SmartRedis))\nare implementations of Redis clients that implement the RedisAI\nAPI with additions specific to scientific workflows.\n\nSmartRedis clients are available in Fortran, C, C++, and Python.\nUsers can seamlessly pull and push data from the Orchestrator from different languages.\n\n## Tensors\n\nTensors are the fundamental data structure for the SmartRedis clients. The Clients\nuse the native array format of the language. For example, in Python, a tensor is\na NumPy array while the C/C++ clients accept nested and contiguous arrays.\n\nWhen stored in the database, all tensors are stored in the same format. Hence,\nany language can receive a tensor from the database no matter what supported language\nthe array was sent from. This enables applications in different languages to communicate\nnumerical data with each other at runtime.\n\nFor more information on the tensor data structure, see\n[the documentation](https://www.craylabs.org/docs/sr_data_structures.html#tensor)\n\n## Datasets\n\nDatasets are collections of Tensors and associated metadata. The ``Dataset`` class\nis a user space object that can be created, added to, sent to, and retrieved from\nthe Orchestrator.\n\nFor an example of how to use the ``Dataset`` class, see the [Online Analysis example](#online-analysis)\n\nFor more information on the API, see the\n[API documentation](https://www.craylabs.org/docs/sr_data_structures.html#dataset)\n\n# SmartSim + SmartRedis Tutorials\n\nSmartSim and SmartRedis were designed to work together. When launched through\nSmartSim, applications using the SmartRedis clients are directly connected to\nany Orchestrator launched in the same [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment).\n\nIn this way, a SmartSim [Experiment](https://www.craylabs.org/docs/api/smartsim_api.html#experiment) becomes a driver for coupled ML and Simulation\nworkflows. The following are simple examples of how to use SmartSim and SmartRedis\ntogether.\n\n## Run the Tutorials\n\nEach tutorial is a Jupyter notebook that can be run through the\n[SmartSim Tutorials docker image](https://github.com/orgs/CrayLabs/packages?repo_name=SmartSim)\nwhich will run a jupyter lab with the tutorials, SmartSim, and SmartRedis installed.\n\n```bash\ndocker pull ghcr.io/craylabs/smartsim-tutorials:latest\ndocker run -p 8888:8888 ghcr.io/craylabs/smartsim-tutorials:latest\n```\nEach of the following examples can be found in the\n[SmartSim documentation](https://www.craylabs.org/docs/tutorials/getting_started/getting_started.html).\n\n## Online Analysis\n\nUsing SmartSim, HPC applications can be monitored in real time by streaming data\nfrom the application to the database. SmartRedis clients can retrieve the\ndata, process, analyze it, and finally store any updated data back to the database for\nuse by other clients.\n\nThe following is an example of how a user could monitor and analyze a simulation.\nThe example here uses the Python client; however, SmartRedis clients are also available\nfor C, C++, and Fortran. All SmartRedis clients implement the same API.\n\nThe example will produce [this visualization](https://user-images.githubusercontent.com/13009163/127622717-2c9e4cfd-50f4-4d94-88c4-8c05fa2fa616.mp4) while the simulation is running.\n\n#### Lattice Boltzmann Simulation\n\nUsing a [Lattice Boltzmann Simulation](https://en.wikipedia.org/wiki/Lattice_Boltzmann_methods),\nthis example demonstrates how to use the SmartRedis ``Dataset`` API to stream\ndata over the Orchestrator deployed by SmartSim.\n\nThe simulation will be composed of two parts: `fv_sim.py` which will generate data from\nthe Simulation and store it in the Orchestrator, and `driver.py`\nwhich will launch the Orchestrator, start `fv_sim.py` and check for data posted to the\nOrchestrator to plot updates in real-time.\n\nThe following code highlights the sections of `fv_sim.py` that are responsible for\ntransmitting the data needed to plot timesteps of the simulation to the Orchestrator.\n\n```Python\n# fv_sim.py\nfrom smartredis import Client\nimport numpy as np\n\n# initialization code omitted\n\n# save cylinder location to database\ncylinder = (X - x_res/4)**2 + (Y - y_res/2)**2 < (y_res/4)**2 # bool array\nclient.put_tensor(\"cylinder\", cylinder.astype(np.int8))\n\nfor time_step in range(steps): # simulation loop\n for i, cx, cy in zip(idxs, cxs, cys):\n F[:,:,i] = np.roll(F[:,:,i], cx, axis=1)\n F[:,:,i] = np.roll(F[:,:,i], cy, axis=0)\n\n bndryF = F[cylinder,:]\n bndryF = bndryF[:,[0,5,6,7,8,1,2,3,4]]\n\n rho = np.sum(F, 2)\n ux = np.sum(F * cxs, 2) / rho\n uy = np.sum(F * cys, 2) / rho\n\n Feq = np.zeros(F.shape)\n for i, cx, cy, w in zip(idxs, cxs, cys, weights):\n Feq[:,:,i] = rho * w * ( 1 + 3*(cx*ux+cy*uy) + 9*(cx*ux+cy*uy)**2/2 - 3*(ux**2+uy**2)/2 )\n F += -(1.0/tau) * (F - Feq)\n F[cylinder,:] = bndryF\n\n # Create a SmartRedis dataset with vorticity data\n dataset = Dataset(f\"data_{str(time_step)}\")\n dataset.add_tensor(\"ux\", ux)\n dataset.add_tensor(\"uy\", uy)\n\n # Put Dataset in db at key \"data_{time_step}\"\n client.put_dataset(dataset)\n```\n\nThe driver script, `driver.py`, launches the Orchestrator database and runs\nthe simulation in a non-blocking fashion. The driver script then uses the SmartRedis\nclient to pull the DataSet and plot the vorticity while the simulation is running.\n\n```Python\n# driver.py\ntime_steps, seed = 3000, 42\n\nexp = Experiment(\"finite_volume_simulation\", launcher=\"local\")\n\ndb = exp.create_database(port=6780, # database port\n interface=\"lo\") # network interface db should listen on\n\n# create the lb simulation Model reference\nsettings = exp.create_run_settings(\"python\",\n exe_args=[\"fv_sim.py\",\n f\"--seed={seed}\",\n f\"--steps={time_steps}\"])\nmodel = exp.create_model(\"fv_simulation\", settings)\nmodel.attach_generator_files(to_copy=\"fv_sim.py\")\nexp.generate(db, model, overwrite=True)\n\nexp.start(db)\nclient = Client(address=db.get_address()[0], cluster=False)\n\n# start simulation (non-blocking)\nexp.start(model, block=False, summary=True)\n\n# poll until simulation starts and then retrieve data\nclient.poll_key(\"cylinder\", 200, 100)\ncylinder = client.get_tensor(\"cylinder\").astype(bool)\n\nfor i in range(0, time_steps):\n client.poll_key(f\"data_{str(i)}\", 10, 1000)\n dataset = client.get_dataset(f\"data_{str(i)}\")\n ux, uy = dataset.get_tensor(\"ux\"), dataset.get_tensor(\"uy\")\n\n # analysis/plotting code omitted\n\nexp.stop(db)\n```\n\nFor more examples of how to use SmartSim and SmartRedis together to perform\nonline analysis, please see the\n[online analsysis tutorial section](https://www.craylabs.org/docs/tutorials/online_analysis/lattice/online_analysis.html) of the\nSmartSim documentation.\n\n## Online Processing\n\nEach of the SmartRedis clients can be used to remotely execute\n[TorchScript](https://pytorch.org/docs/stable/jit.html) code on data\nstored within the database. The scripts/functions are executed in the Torch\nruntime linked into the database.\n\nAny of the functions available in the\n[TorchScript builtins](https://pytorch.org/docs/stable/jit_builtin_functions.html#builtin-functions)\ncan be saved as \"script\" or \"functions\" in the database and used directly by\nany of the SmartRedis Clients.\n\n### Singular Value Decomposition\n\nFor example, the following code sends the built-in\n[Singular Value Decomposition](https://pytorch.org/docs/stable/generated/torch.svd.html)\nto the database and execute it on a dummy tensor.\n\n```python\nimport numpy as np\nfrom smartredis import Client\n\n# don't even need to import torch\ndef calc_svd(input_tensor):\n return input_tensor.svd()\n\n\n# connect a client to the database\nclient = Client(cluster=False)\n\n# get dummy data\ntensor = np.random.randint(0, 100, size=(5, 3, 2)).astype(np.float32)\n\nclient.put_tensor(\"input\", tensor)\nclient.set_function(\"svd\", calc_svd)\n\nclient.run_script(\"svd\", \"calc_svd\", \"input\", [\"U\", \"S\", \"V\"])\n# results are not retrieved immediately in case they need\n# to be fed to another function/model\n\nU = client.get_tensor(\"U\")\nS = client.get_tensor(\"S\")\nV = client.get_tensor(\"V\")\nprint(f\"U: {U}, S: {S}, V: {V}\")\n```\n\nThe processing capabilities make it simple to form computational pipelines of\nfunctions, scripts, and models.\n\nSee the full [TorchScript Language Reference](https://pytorch.org/docs/stable/jit.html#torchscript-language)\ndocumentation for more information on available methods, functions, and how\nto create your own.\n\n## Online Inference\n\nSmartSim supports the following frameworks for querying Machine Learning models\nfrom C, C++, Fortran and Python with the SmartRedis Clients:\n\n<table>\n <thead>\n <tr>\n <th style=\"text-align:center\">RedisAI Version</th>\n <th style=\"text-align:center\">Libraries</th>\n <th style=\"text-align:center\">Supported Version</th>\n </tr>\n </thead>\n <tbody style=\"text-align:center\">\n <tr>\n <td rowspan=\"3\">1.2.7</td>\n <td>PyTorch</td>\n <td>2.1.0</td>\n </tr>\n <tr>\n <td>TensorFlow\\Keras</td>\n <td>2.15.0</td>\n </tr>\n <tr>\n <td>ONNX</td>\n <td>1.14.1</td>\n </tr>\n </tbody>\n</table>\n\nA [number of other libraries](https://github.com/onnx/onnxmltools) are\nsupported through ONNX, like [SciKit-Learn](https://github.com/onnx/sklearn-onnx/)\nand [XGBoost](https://github.com/onnx/onnxmltools/tree/master/tests/xgboost).\n\n**Note:** It's important to remember that SmartSim utilizes a client-server model. To run\nexperiments that utilize the above frameworks, you must first start the Orchestrator\ndatabase with SmartSim.\n\n### PyTorch CNN Example\n\nThe example below shows how to spin up a database with SmartSim and\ninvoke a PyTorch CNN model using the SmartRedis clients.\n\n```python\n# simple_torch_inference.py\nimport io\nimport torch\nimport torch.nn as nn\nfrom smartredis import Client\nfrom smartsim import Experiment\n\nexp = Experiment(\"simple-online-inference\", launcher=\"local\")\ndb = exp.create_database(port=6780, interface=\"lo\")\n\nclass Net(nn.Module):\n def __init__(self):\n super().__init__()\n self.conv = nn.Conv2d(1, 1, 3)\n\n def forward(self, x):\n return self.conv(x)\n\ntorch_model = Net()\nexample_forward_input = torch.rand(1, 1, 3, 3)\nmodule = torch.jit.trace(torch_model, example_forward_input)\nmodel_buffer = io.BytesIO()\ntorch.jit.save(module, model_buffer)\n\nexp.start(db, summary=True)\n\naddress = db.get_address()[0]\nclient = Client(address=address, cluster=False)\n\nclient.put_tensor(\"input\", example_forward_input.numpy())\nclient.set_model(\"cnn\", model_buffer.getvalue(), \"TORCH\", device=\"CPU\")\nclient.run_model(\"cnn\", inputs=[\"input\"], outputs=[\"output\"])\noutput = client.get_tensor(\"output\")\nprint(f\"Prediction: {output}\")\n\nexp.stop(db)\n```\n\nThe above python code can be run like any normal python script:\n```bash\npython simple_torch_inference.py\n```\n\nFor more examples of how to use SmartSim and SmartRedis together to perform\nonline inference, please see the\n[online inference tutorials section](https://www.craylabs.org/docs/tutorials/ml_inference/Inference-in-SmartSim.html) of the\nSmartSim documentation.\n\n--------\n\n# Publications\n\nThe following are public presentations or publications using SmartSim\n\n - [Collaboration with NCAR - CGD Seminar](https://www.youtube.com/watch?v=2e-5j427AS0)\n - [SmartSim: Using Machine Learning in HPC Simulations](https://arxiv.org/abs/2104.09355)\n - [SmartSim: Online Analytics and Machine Learning for HPC Simulations](https://www.youtube.com/watch?v=JsSgq-fq44w&list=PLuQQBBQFfpgq0OvjKbjcYgTDzDxTqtwua&index=11)\n - [PyTorch Ecosystem Day Poster](https://assets.pytorch.org/pted2021/posters/J8.png)\n\n\n--------\n# Cite\n\nPlease use the following citation when referencing SmartSim, SmartRedis, or any SmartSim related work:\n\nPartee et al., \u201cUsing Machine Learning at Scale in HPC Simulations with SmartSim:\nAn Application to Ocean Climate Modeling\u201d, Journal of Computational Science, Volume 62, 2022, 101707, ISSN 1877-7503\n\nAvailable: https://doi.org/10.1016/j.jocs.2022.101707.\n\n## bibtex\n\n\n```latex\n@article{PARTEE2022101707,\n title = {Using Machine Learning at scale in numerical simulations with SmartSim: An application to ocean climate modeling},\n journal = {Journal of Computational Science},\n volume = {62},\n pages = {101707},\n year = {2022},\n issn = {1877-7503},\n doi = {https://doi.org/10.1016/j.jocs.2022.101707},\n url = {https://www.sciencedirect.com/science/article/pii/S1877750322001065},\n author = {Sam Partee and Matthew Ellis and Alessandro Rigazzi and Andrew E. Shao and Scott Bachman and Gustavo Marques and Benjamin Robbins},\n keywords = {Deep learning, Numerical simulation, Climate modeling, High performance computing, SmartSim},\n}\n```\n",
"bugtrack_url": null,
"license": "BSD 2-Clause License",
"summary": "AI Workflows for Science",
"version": "0.8.0",
"project_urls": {
"Documentation": "https://www.craylabs.org",
"Homepage": "https://github.com/CrayLabs/SmartSim",
"Source": "https://github.com/CrayLabs/SmartSim"
},
"split_keywords": [
"scientific",
" ai",
" workflow",
" hpc",
" analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e61110e17b95b8ead8ff63acb9485ec3b58df8f207dac55b7dcf53f501420be7",
"md5": "ed6dbe3f2da48717be18d411a7b61b45",
"sha256": "fe1ca9c03f7cf5deb4e16338a225251714258d6a95b806c35ac5f95facea31d2"
},
"downloads": -1,
"filename": "smartsim-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed6dbe3f2da48717be18d411a7b61b45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 465727,
"upload_time": "2024-09-27T21:43:24",
"upload_time_iso_8601": "2024-09-27T21:43:24.159736Z",
"url": "https://files.pythonhosted.org/packages/e6/11/10e17b95b8ead8ff63acb9485ec3b58df8f207dac55b7dcf53f501420be7/smartsim-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad8eea19f09edc4cc5a544f1185b7b362d28141f9283bd9ab5878777fa300e5a",
"md5": "aa14db07a7032e228fa6bdd1ae368ff7",
"sha256": "7d97184c05c897e4428534122f288134fdd26701a53f6acb07fe2ca8555e5073"
},
"downloads": -1,
"filename": "smartsim-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "aa14db07a7032e228fa6bdd1ae368ff7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 405599,
"upload_time": "2024-09-27T21:43:25",
"upload_time_iso_8601": "2024-09-27T21:43:25.719563Z",
"url": "https://files.pythonhosted.org/packages/ad/8e/ea19f09edc4cc5a544f1185b7b362d28141f9283bd9ab5878777fa300e5a/smartsim-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-27 21:43:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CrayLabs",
"github_project": "SmartSim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smartsim"
}
JSON
