2.4 External Tools

Note: This example is deprecated for the latest versions of signac and signac-flow.

The following section demonstrates how to use the signac command line interface (CLI) in conjunction with other tools.

%%sh
signac --help

usage: signac [-h] [--debug] [--version] [-v] [-y]
              {init,project,job,statepoint,diff,document,rm,move,clone,index,find,view,schema,shell,sync,import,export,update-cache,config}
              ...

signac aids in the management, access and analysis of large-scale
computational investigations.

positional arguments:
  {init,project,job,statepoint,diff,document,rm,move,clone,index,find,view,schema,shell,sync,import,export,update-cache,config}

optional arguments:
  -h, --help            show this help message and exit
  --debug               Show traceback on error for debugging.
  --version             Display the version number and exit.
  -v, --verbosity       Set level of verbosity.
  -y, --yes             Answer all questions with yes. Useful for scripted
                        interaction.

To interact with a project on the command line, the current working directory needs to be within or below the project root directory. Let’s start by reseting the designated project root directory for this section of the tutorial.

%pwd
%rm -rf projects/tutorial/cli
%mkdir -p projects/tutorial/cli
%cp idg projects/tutorial/cli

Next we switch the current working directory to the project root directory.

%cd projects/tutorial/cli

notebooks/projects/tutorial/cli

Then we initialize the project.

%%sh
signac init TutorialCLIProject

Initialized project 'TutorialCLIProject'.

We can verify the project configuration.

%%sh
signac project
signac project --workspace

TutorialCLIProject
notebooks/projects/tutorial/cli/workspace

We access the job handle by providing the state point on the command line in JSON format.

%%sh
signac job '{"kT": 1.0, "p": 1.0, "N": 1000}'

ee617ad585a90809947709a7a45dda9a

The statepoints could also be read from STDIN, e.g., by reading it from a file. Let’s create a statepoints file with three statepoints:

%%sh
echo '{"kT": 1.0, "p": 0.1, "N": 1000}' > statepoints.txt
echo '{"kT": 1.0, "p": 1.0, "N": 1000}' >> statepoints.txt
echo '{"kT": 1.0, "p": 10.0, "N": 1000}' >> statepoints.txt

cat statepoints.txt

{"kT": 1.0, "p": 0.1, "N": 1000}
{"kT": 1.0, "p": 1.0, "N": 1000}
{"kT": 1.0, "p": 10.0, "N": 1000}

We can pipe the content of this file into the signac CLI to get the corresponding job id.

%%sh
head -n 1 statepoints.txt | signac job

5a6c687f7655319db24de59a2336eff8

Instead of the job id, we can directly obtain the path to the job workspace.

%%sh
head -n 1 statepoints.txt | signac job --workspace

notebooks/projects/tutorial/cli/workspace/5a6c687f7655319db24de59a2336eff8

That’s specifically useful in conjunction with external tools. Let’s pretend that we need to use a program called idg to calculate the ideal gas equation.

The idg program will calculate the volume of an ideal gas given the input parameters p, kT and N, just like in the previous sections.

%%sh
./idg -p 1.0 -N 1000 --kT 1.0

1000.0

We can store the result in a file based on the input arguments using the -cw argument, short for --create --workspace, which returns the workspace path and creates it if necessary.

%%sh
./idg -p 1.0 --kT 1.0 -N 1000 > $(signac job -cw '{"p": 1.0, "kT": 1.0, "N": 1000}')/V.txt

Obviously, we wouldn’t write these commands all manually, but use a script instead.

import json

import signac

project = signac.get_project()
for p in 0.1, 1.0, 10.0:
    job = project.open_job({"N": 1000, "p": p, "kT": 1.0})
    cmd = "./idg -p {p} --kT {kT} -N {N}".format(**job.statepoint())
    cmd += " > $(signac job -cw '{}')/V.txt".format(json.dumps(job.statepoint()))
    print(cmd)

./idg -p 0.1 --kT 1.0 -N 1000 > $(signac job -cw '{"N": 1000, "p": 0.1, "kT": 1.0}')/V.txt
./idg -p 1.0 --kT 1.0 -N 1000 > $(signac job -cw '{"N": 1000, "p": 1.0, "kT": 1.0}')/V.txt
./idg -p 10.0 --kT 1.0 -N 1000 > $(signac job -cw '{"N": 1000, "p": 10.0, "kT": 1.0}')/V.txt

We can then execute this script…

%%sh
./idg -p 0.1 --kT 1.0 -N 1000 > $(signac job -cw '{"kT": 1.0, "p": 0.1, "N": 1000}')/V.txt
./idg -p 1.0 --kT 1.0 -N 1000 > $(signac job -cw '{"kT": 1.0, "p": 1.0, "N": 1000}')/V.txt
./idg -p 10.0 --kT 1.0 -N 1000 > $(signac job -cw '{"kT": 1.0, "p": 10.0, "N": 1000}')/V.txt

… and examine the results.

%cat `signac project -w`/*/V.txt

100.0
10000.0
1000.0