Contents

Developer

Developer

This section details common practices and tips for contributors to SmartSim and SmartRedis.

Testing SmartSim

Note

This section describes how to run the SmartSim (infrastructure library) test suite. For testing SmartRedis, see below

SmartSim utilizes Pytest for running its test suite. In the top level of SmartSim, users can run multiple testing commands with the developer Makefile

Test
-------
test                       - Build and run all tests
test-verbose               - Build and run all tests [verbosely]
test-cov                   - run python tests with coverage

Note

For the test to run, you must have the requirements-dev.txt dependencies installed in your python environment.

Local

There are two levels of testing in SmartSim. The first runs by default and does not launch any jobs out onto a system through a workload manager like Cobalt.

If any of the above commands are used, the test suite will run the “light” test suite by default.

PBSPro, Slurm, Cobalt, LSF

To run the full test suite, users will have to be on a system with one of the above workload managers. Additionally, users will need to obtain an allocation of at least 3 nodes.

# for slurm (with srun)
salloc -N 3 -A account --exclusive -t 00:10:00

# for PBSPro (with aprun)
qsub -l select=3 -l place=scatter -l walltime=00:10:00 -q queue

# for Cobalt (with aprun)
qsub -n 3 -t 00:10:00 -A account -q queue -I

# for LSF (with jsrun)
bsub -Is -W 00:30 -nnodes 3 -P project $SHELL

Values for queue, account, or project should be substituted appropriately.

Once in an iterative allocation, users will need to set the test launcher environment variable: SMARTSIM_TEST_LAUNCHER to one of the following values

  • slurm

  • cobalt

  • pbs

  • lsf

  • local

If tests have to run on an account or project, the environment variable SMARTSIM_TEST_ACCOUNT can be set.

Testing SmartRedis

The following will demonstrate how to build and run the tests for each of the SmartSim clients.

Building the Tests

Before building the tests, it is assumed that the base dependencies for SmartRedis described in the installation instructions have already been executed.

To build the tests, you first need to install the dependencies for testing. To download SmartRedis related testing dependencies, run the following:

make test-deps

If you wish to run tests on GPU hardware, run the following command:

make test-deps-gpu

Note

The test suite is currently written to be run on CPU hardware to test model and script executions. Testing on GPU hardware currently requires modifications to the test suite.

Note

The tests require

  • GCC > 5

  • CMake > 3

Since these are usually system libraries, we do not install them for the user

After installing dependencies and setting up your testing environment with setup_test_env.sh, all tests can be built with the following command:

./setup_test_env.sh
make build-tests

Starting Redis

Before running the tests, users will have to spin up a Redis cluster instance and set the SSDB environment variable.

To spin up a local Redis cluster, use the script in utils/create_cluster as follows:

cd /smartredis                 # navigate to the top level dir of smartredis
conda activate env             # activate python env with SmartRedis requirements
source setup_test_env.sh       # Setup smartredis environment
cd utils/create_cluster
python local_cluster.py        # spin up Redis cluster locally
export SSDB="127.0.0.1:6379,127.0.0.1:6380,127.0.0.1:6381"  # Set database location

# run the tests (described below)

cd utils/create_cluster
python local_cluster.py --stop # stop the Redis cluster

A similar script utils/create_cluster/slurm_cluster.py assists with launching a Redis cluster for testing on Slurm managed machines. This script has only been tested on a Cray XC, and it may not be portable to all machines.

Running the Tests

Note

If you are running the tests in a new terminal from the one used to build the tests and run the Redis cluster, remember to load your python environment with SmartRedis dependencies, source the setup_test_env.sh file, and set the SSDB environment variable.

To build and run all tests, run the following command in the top level of the smartredis repository.

make test

You can also run tests for individual clients as follows:

make test-c         # run C tests
make test-fortran   # run Fortran tests
make test-cpp       # run all C++ tests
make unit-test-cpp  # run unit tests for C++
make test-py        # run Python tests
make testpy-cov     # run python tests with coverage
make testcpp-cpv    # run cpp unit tests with coverage

Git Workflow

Setup

  • Fork the SmartSim (SmartRedis) repository

  • The origin remote should be set to your fork for pull and push

  • Set upstream as the main repository and set upstream push remote to no_push

  • Follow installation instructions

Pull Requests

Please check the following before submitting a pull request to the SmartSim repository

  1. Your feature is on a new branch off master.

  2. You are merging the feature branch from your fork into the main repository.

  3. All unnecessary whitespace has been purged from your code.

  4. For Python code changes, Black and isort have been applied to format code and sort imports.

  5. Pylint errors have been minimized as much as possible.

  6. All your code has been appropriately documented.

  7. The PR description is clear and concise.

  8. You have requested a review.

Merging

When merging, there are a few guidelines to follow

  • Wrap all merge messages to 70 characters per line.

Python Guidelines

For the most part, the conventions are to follow PEP8 that is supplied by pylint. However, there are a few things to specifically mention.

  • Underscores should precede methods not meant to be used outside a class

  • All methods should have docstrings (with some exceptions)

  • Variable names should accurately capture what values it is storing without being overly verbose

  • No bad words

  • Use Black and isort frequently

  • Utilize conftest.py for creating pytest fixtures

SmartSim Python Style Guide Do’s and Don’ts:

  • DON’T use global variables or the global keyword unless necessary

  • DON’T over comment code when it reads like English

  • DO use underscores on methods that should not be used outside a class

  • DO use comprehensions

  • DON’T write functions for more than one purpose

  • DON’T allow functions to return more than one type

  • DON’T use protected member variables outside a class

  • DON’T use single letter variable names

  • DO use entire words in names (i.e. get_function not get_func)

  • DON’T use wildcard imports (i.e. from package import *) unless __all__ is defined

  • DO use snake_case when naming functions, methods, and variables

  • DO use PascalCase when naming Classes

  • DO use the logging module

Editor Suggestions

The editor that we suggest developers use is VSCode. Below are some extensions that could make the process of developing on SmartSim a bit easier.

  • GitLens, for viewing changes in the git history

  • Remote SSH, for connecting to clusters and supercomputers

  • PyLance, Language Server

  • Python indent, for correcting python indents

  • reStructuredText, for writing documentation

  • Strict Whitespace, for ensuring no whitespace left in code

  • Python Docstring Generator, for writing docstring quickly

  • C/C++, for client development

  • Settings Sync, for syncing settings across remote servers

previous

Code of Conduct