The signac framework offers both a Python and a command-line interface.

Python interface

The following code snippets show some examples on how to interact with a signac project.

Setup a project

We initialize a project in the local directory with:

import signac
project = signac.init_project('MyProject')

This provides us access to the project interface. After initialization, we can also access the project with project = signac.get_project().

Manage data

In the context of a signac project, all data is uniquely addressable by a specific state point (a set of key-value pairs, e.g., a dict).

Let’s calculate the volume of an ideal gas at different pressures p, but constant temperature kT and system size N. We will use signac to keep track of metadata (the state point) and data (the volume):

# Iterate over the variable of interest:
for p in 0.1, 1.0, 10.0:

    # Obtain a handle for the full state point:
    job = project.open_job({'p': p, 'kT': 1.0, 'N': 1000})

    # Either store the volume as document-oriented data:
    job.doc.volume = job.sp.N * job.sp.kT / job.sp.p

    # Or write it to a file within the job's workspace:
    with job:
        with open('volume.txt', 'w') as file:
            file.write(str(job.sp.N * job.sp.kT / job.sp.p))

Find data

We can then iterate over the data space to access both metadata and data:

for job in project:
    print(job.sp.p, job.doc.volume)

    with open(job.fn('volume.txt')) as file:

We can select a specific data subspace, using a filter argument:

for job in project.find_jobs({'kT': 1.0}):
    print(job.sp.p, job.doc.volume)

This would give us the pressure and volume only where the temperature T is equal to 1.0.

Alternatively, we can select all jobs with a specific volume, using a document filter:

for job in project.find_jobs(doc_filter={'volume': 100}):

Of course, both filters may be used in combination.

Command line interface

The command line interface is designed to support workflows that are not Python-driven:

Setup a project

Initialize the project in the current root directory:

$ signac init MyProject

Manage data

Write data to a file located in the job’s workspace:

$ echo "world!" >> `signac job '{"a": 42}' -cw`/hello.txt

Find data

Select data subspaces directly on the command line:

$ signac find a 42

A reference of the full command line interface can be accessed via:

$ signac --help

What’s next?

If you are interested in learning more, we recommend to go through the resources listed on the Support page!