This is a collection of example projects which are designed to illustrate how to implement certain applications and solutions with signac. Unlike the tutorial, the examples consist mainly of complete, immediately executable source code with less explanation.

Ideal Gas

This example is based on the Tutorial and assumes that we want to model a system using the ideal gas law:

\[p V = N k_B T\]

The data space is initialized for a specific system size \(N\), thermal energy \(kT\), and pressure \(p\) in a script called init.py:

# init.py
import signac

project = signac.init_project('ideal-gas-project')

for p in range(1, 11):
    sp = {'p': p, 'kT': 1.0, 'N': 1000}
    job = project.open_job(sp)

The workflow consists of a compute_volume operation that computes the volume based on the given parameters and stores it within a file called V.txt within each job’s workspace directory. The two additional operations copy the result into a JSON file called data.json and into the job document under the volume key respectively. All operations are defined in project.py:

# project.py
from flow import FlowProject

def volume_computed(job):
    return job.isfile("volume.txt")

def compute_volume(job):
    volume = job.sp.N * job.sp.kT / job.sp.p
    with open(job.fn("volume.txt"), "w") as file:
        file.write(str(volume) + "\n")

def store_volume_in_json_file(job):
    import json
    with open(job.fn("volume.txt")) as textfile:
        with open(job.fn("data.json"), "w") as jsonfile:
            data = {"volume": float(textfile.read())}
            jsonfile.write(json.dumps(data) + "\n")

@FlowProject.post(lambda job: 'volume' in job.document)
def store_volume_in_document(job):
    with open(job.fn("volume.txt")) as textfile:
        job.document.volume = float(textfile.read())

if __name__ == '__main__':

The complete workflow can be executed on the command line with $ python project.py run.

MD with HOOMD-blue

This example demonstrates how to setup and analyze the simulation of a Lennard-Jones fluid with molecular dynamics (MD) using HOOMD-blue. The project data space is initialized in a src/init.py script with explicit random seed:

#!/usr/bin/env python
"""Initialize the project's data space.

Iterates over all defined state points and initializes
the associated job workspace directories."""
import logging
import argparse
from hashlib import sha1

import signac
import numpy as np

def main(args, random_seed):
    project = signac.init_project('Ideal-Gas-Example-Project')
    for replication_index in range(args.num_replicas):
        for p in np.linspace(0.5, 5.0, 10):
            statepoint = dict(
                    # system size

                    # Lennard-Jones potential parameters

                    # random seed
                    seed=random_seed*(replication_index + 1),

                    # thermal energy
                    # presure
                    # thermostat coupling constant
                    # barostat coupling constant

if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description="Initialize the data space.")
        help="A string to generate a random seed.")
        '-n', '--num-replicas',
        help="Initialize multiple replications.")
    args = parser.parse_args()

    # Generate an integer from the random str.
        random_seed = int(args.random)
    except ValueError:
        random_seed = int(sha1(args.random.encode()).hexdigest(), 16) % (10 ** 8)

    main(args, random_seed)

Using this script, one replica set (for a given random seed, e.g., 42) can then be initialized with:

$ python src/init.py 42

The simulation and analysis workflow is broken into three operations:

  1. init: Initialize the simulation configuration.
  2. estimate: Use the ideal gas law to estimate the expected volume.
  3. sample: Carry out the simulation with HOOMD-blue.

Those three operations and corresponding condition functions are defined and implemented within a src/project.py module:

"""This module contains the operation functions for this project.

The workflow defined in this file can be executed from the command
line with

    $ python src/project.py run [job_id [job_id ...]]

See also: $ python src/project.py --help
from flow import FlowProject

class Project(FlowProject):

def initialize(job):
    "Initialize the simulation configuration."
    import hoomd
    from math import ceil
    if hoomd.context.exec_conf is None:
    with job:
        with hoomd.context.SimulationContext():
            n = int(ceil(pow(job.sp.N, 1.0/3)))
            assert n**3 == job.sp.N
            hoomd.init.create_lattice(unitcell=hoomd.lattice.sc(a=1.0), n=n)
            hoomd.dump.gsd('init.gsd', period=None, group=hoomd.group.all())

@Project.post(lambda job: 'volume_estimate' in job.document)
def estimate(job):
    "Ideal-gas estimate operation."
    # Calculate volume using ideal gas law
    V = job.sp.N * job.sp.kT / job.sp.p
    job.document.volume_estimate = V

def current_step(job):
    import gsd.hoomd
    if job.isfile('dump.gsd'):
        with gsd.hoomd.open(job.fn('dump.gsd')) as traj:
            return traj[-1].configuration.step
    return -1

def sampled(job):
    return current_step(job) >= 5000

def progress(job):
    return '{}/4'.format(int(round(current_step(job) / 5000) * 4))

def sample(job):
    "Sample operation."
    import logging
    import hoomd
    from hoomd import md
    if hoomd.context.exec_conf is None:
    with job:
        with hoomd.context.SimulationContext():
            hoomd.init.read_gsd('init.gsd', restart='restart.gsd')
            group = hoomd.group.all()
            gsd_restart = hoomd.dump.gsd(
                'restart.gsd', truncate=True, period=100, phase=0, group=group)
            lj = md.pair.lj(r_cut=job.sp.r_cut, nlist=md.nlist.cell())
            lj.pair_coeff.set('A', 'A', epsilon=job.sp.epsilon, sigma=job.sp.sigma)
                group=group, kT=job.sp.kT, tau=job.sp.tau,
                P=job.sp.p, tauP=job.sp.tauP)
            hoomd.analyze.log('dump.log', ['volume'], period=100)
            hoomd.dump.gsd('dump.gsd', period=100, group=hoomd.group.all())
            except hoomd.WalltimeLimitReached:
                logging.warning("Reached walltime limit.")
                job.document['sample_step'] = hoomd.get_step()

if __name__ == '__main__':

There are two additional label functions, which show whether the simulation has finished (sampled) and one that shows the rough progress in quarters (progress).

Execute the initialization and simulation with:

$ python src/project.py run

Integration with Sacred

Integrating a sacred experiment with signac-flow is very simple. Assuming the following sacred experiment defined in a experiment.py module:

from sacred import Experiment

ex = Experiment()

def hello(foo):
    print('hello', foo)

if __name__ == '__main__':

Then we can integrate that experiment on a per job basis like this:

from flow import FlowProject
from sacred.observers import FileStorageObserver

from experiment import ex

class SacredProject(FlowProject):

def run_experiment(job):
    ex.add_config(** job.sp())
    ex.observers[:] = [FileStorageObserver.create(job.fn('my_runs'))]

if __name__ == '__main__':