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.
[1]:
%%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.
[2]:
%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.
[3]:
%cd projects/tutorial/cli
notebooks/projects/tutorial/cli
Then we initialize the project.
[4]:
%%sh
signac init TutorialCLIProject
Initialized project 'TutorialCLIProject'.
We can verify the project configuration.
[5]:
%%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.
[6]:
%%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:
[7]:
%%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.
[8]:
%%sh
head -n 1 statepoints.txt | signac job
5a6c687f7655319db24de59a2336eff8
Instead of the job id, we can directly obtain the path to the job workspace.
[9]:
%%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.
[10]:
%%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.
[11]:
%%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.
[12]:
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…
[13]:
%%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.
[14]:
%cat `signac project -w`/*/V.txt
100.0
10000.0
1000.0