Command Line Interface¶
Overview
The following core signac functions are—in addition to the Python interface—accessible
directly via the $ signac command.
init¶
usage: signac init [-h] [-w WORKSPACE] project_id
positional arguments:
project_id Initialize a project with the given project id.
optional arguments:
-h, --help show this help message and exit
-w WORKSPACE, --workspace WORKSPACE
The path to the workspace directory.
project¶
usage: signac project [-h] [-w] [-i] [-a]
optional arguments:
-h, --help show this help message and exit
-w, --workspace Print the project's workspace path instead of the project
id.
-i, --index Generate and print an index for the project.
-a, --access Create access module for indexing.
job¶
usage: signac job [-h] [-w] [-c] [statepoint]
positional arguments:
statepoint The job's statepoint in JSON format. Omit this argument to
read from STDIN.
optional arguments:
-h, --help show this help message and exit
-w, --workspace Print the job's workspace path instead of the job id.
-c, --create Create the job's workspace directory if necessary.
statepoint¶
usage: signac statepoint [-h] [-p [PRETTY]] [-i [INDENT]] [-s]
[job_id [job_id ...]]
Print the statepoint(s) corresponding to one or more job ids.
positional arguments:
job_id One or more job ids. The corresponding jobs must be
initialized.
optional arguments:
-h, --help show this help message and exit
-p [PRETTY], --pretty [PRETTY]
Print state point in pretty format. An optional
argument to this flag specifies the maximal depth a
state point is printed.
-i [INDENT], --indent [INDENT]
Specify the indentation of the JSON formatted state
point.
-s, --sort Sort the state point keys for output.
diff¶
usage: signac diff [-h] [-p [PRETTY]] [-i [INDENT]] [-f FILTER [FILTER ...]]
[-d DOC_FILTER [DOC_FILTER ...]]
[job_id [job_id ...]]
Find the difference among job state points.
positional arguments:
job_id One or more job ids. The corresponding jobs must be
initialized.
optional arguments:
-h, --help show this help message and exit
-p [PRETTY], --pretty [PRETTY]
Print state point in pretty format. An optional
argument to this flag specifies the maximal depth a
state point is printed.
-i [INDENT], --indent [INDENT]
Specify the indentation of the JSON formatted state
point.
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Limit the diff to jobs matching this state point
filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Show documents of jobs matching this document filter.
document¶
usage: signac document [-h] [-p [PRETTY]] [-i [INDENT]] [-s]
[-f FILTER [FILTER ...]]
[-d DOC_FILTER [DOC_FILTER ...]] [--index INDEX]
[job_id [job_id ...]]
Print the document(s) corresponding to one or more job ids.
positional arguments:
job_id One or more job ids. The job corresponding to a job id
must be initialized.
optional arguments:
-h, --help show this help message and exit
-p [PRETTY], --pretty [PRETTY]
Print document in pretty format. An optional argument
to this flag specifies the maximal depth a document is
printed.
-i [INDENT], --indent [INDENT]
Specify the indentation of the JSON formatted state
point.
-s, --sort Sort the document keys for output in JSON format.
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Show documents of jobs matching this state point
filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Show documents of job matching this document filter.
--index INDEX The filename of an index file.
rm¶
usage: signac rm [-h] [-c] [-i] [-v] job_id [job_id ...]
positional arguments:
job_id One or more job ids of jobs to remove.
optional arguments:
-h, --help show this help message and exit
-c, --clear Do not completely remove, but only clear the job.
-i, --interactive Request confirmation before attempting to remove/clear
each job.
-v, --verbose Be verbose when removing/clearing files.
move¶
usage: signac move [-h] project job_id [job_id ...]
positional arguments:
project The root directory of the project to move one or more jobs to.
job_id One or more job ids. The corresponding jobs must be initialized.
optional arguments:
-h, --help show this help message and exit
clone¶
usage: signac clone [-h] project job_id [job_id ...]
positional arguments:
project The root directory of the project to clone one or more jobs in.
job_id One or more job ids. The corresponding jobs must be initialized.
optional arguments:
-h, --help show this help message and exit
index¶
usage: signac index [-h] [-t TAGS [TAGS ...]] [root]
positional arguments:
root Specify the root path from where the main index is to
be compiled.
optional arguments:
-h, --help show this help message and exit
-t TAGS [TAGS ...], --tags TAGS [TAGS ...]
Specify tags for this main index compilation.
find¶
usage: signac find [-h] [-d DOC_FILTER [DOC_FILTER ...]] [-i INDEX]
[-s [SHOW]] [--sp [SP [SP ...]]] [--doc [DOC [DOC ...]]]
[-p [PRETTY]] [-1]
[filter [filter ...]]
All filter arguments may be provided either directly in JSON encoding or in a
simplified form, e.g., -- $ signac find a 42 -- is equivalent to -- $ signac
find '{"a": 42}'.
positional arguments:
filter A JSON encoded state point filter (key-value pairs).
optional arguments:
-h, --help show this help message and exit
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
A document filter.
-i INDEX, --index INDEX
The filename of an index file.
-s [SHOW], --show [SHOW]
Show the state point and document of each job.
Equivalent to --sp --doc --pretty 3.
--sp [SP [SP ...]] Show the state point of each job. Can be passed the
list of state point keys to print (if they exist for a
given job).
--doc [DOC [DOC ...]]
Show the document of each job. Can be passed the list
of document keys to print (if they exist for a given
job).
-p [PRETTY], --pretty [PRETTY]
Pretty print output when using --sp, --doc, or
---show. Argument is the depth to which keys are
printed.
-1, --one-line Print output in JSON and on one line.
view¶
usage: signac view [-h] [-f FILTER [FILTER ...]]
[-d DOC_FILTER [DOC_FILTER ...]] [-j JOB_ID [JOB_ID ...]]
[-i INDEX]
[prefix] [path]
Generate a human readable set of paths representing state points in the
workspace, e.g.
view/param_name_1/param_value_1/param_name_2/param_value_2/job. The leaf nodes
of this directory structure are symlinks (named "job") into the workspace
directory for that parameter combination. Note that all positional arguments
must be provided before any keyword arguments. In particular, the prefix and
path must be specified before arguments such as the filters, e.g. signac view
$PREFIX $VIEW_PATH -f FILTERS -d DOC_FILTERS.
positional arguments:
prefix The path where the view is to be created. Defaults to
view.
path The path used for the generation of the linked view
hierarchy, defaults to '{{auto}}' (see
Project.export_to for information on how this is
expanded).
optional arguments:
-h, --help show this help message and exit
select:
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Limit the view to jobs matching this state point
filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Limit the view to jobs matching this document filter.
-j JOB_ID [JOB_ID ...], --job-id JOB_ID [JOB_ID ...]
Limit the view to jobs with these job ids.
-i INDEX, --index INDEX
The filename of an index file.
schema¶
usage: signac schema [-h] [-x] [-t DEPTH] [-p PRECISION] [-r MAX_NUM_RANGE]
[-f FILTER [FILTER ...]] [-d DOC_FILTER [DOC_FILTER ...]]
[-j JOB_ID [JOB_ID ...]]
optional arguments:
-h, --help show this help message and exit
-x, --exclude-const Exclude state point parameters, which are constant
over the complete project data space.
-t DEPTH, --depth DEPTH
A non-zero value will format the schema in a nested
representation up to the specified depth. The default
is a flat view (depth=0).
-p PRECISION, --precision PRECISION
Round all numerical values up to the given precision.
-r MAX_NUM_RANGE, --max-num-range MAX_NUM_RANGE
The maximum number of entries shown for a value range,
defaults to 5.
select:
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Detect schema only for jobs that match the state point
filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Detect schema only for jobs that match the document
filter.
-j JOB_ID [JOB_ID ...], --job-id JOB_ID [JOB_ID ...]
Detect schema only for jobs with the given job ids.
shell¶
usage: signac shell [-h] [-c COMMAND] [-f FILTER [FILTER ...]]
[-d DOC_FILTER [DOC_FILTER ...]] [-j JOB_ID [JOB_ID ...]]
[file]
positional arguments:
file Execute Python script in file.
optional arguments:
-h, --help show this help message and exit
-c COMMAND, --command COMMAND
Execute Python program passed as string.
select:
Specify one or more jobs to preset the `jobs` variable as a generator over
all job handles associated with the given selection. If the selection
contains only one job, an additional `job` variable is referencing that
single job, otherwise it is `None`.
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Reduce selection to jobs that match the given filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Reduce selection to jobs that match the given document
filter.
-j JOB_ID [JOB_ID ...], --job-id JOB_ID [JOB_ID ...]
Reduce selection to jobs that match the given job ids.
sync¶
usage: signac sync [-h] [-v] [-a] [-r] [-l] [-p] [-o] [-g] [-t] [-x [EXCLUDE]]
[-I] [--size-only] [--round-times] [-n] [-u]
[-s {always,never,update,Ask}] [-k KEY] [--all-keys]
[--no-keys] [-w] [--force] [-m] [--parallel [PARALLEL]]
[--stats] [-H] [--json] [-f FILTER [FILTER ...]]
[-d DOC_FILTER [DOC_FILTER ...]] [-j JOB_ID [JOB_ID ...]]
source [destination]
Use this command to synchronize this project with another project; similar to
the synchronization of two directories with `rsync`. Data is always copied
from the source to the destination. For example: `signac sync
/path/to/other/project -u --all-keys` means "Synchronize all jobs within this
project with those in the other project; overwrite files if the source files
is newer and overwrite all conflicting keys in the project and job documents."
positional arguments:
source The root directory of the project that this project
should be synchronized with.
destination Optional: The root directory of the project that
should be modified for synchronization, defaults to
the local project.
optional arguments:
-h, --help show this help message and exit
-v, --verbosity Set level of verbosity.
-w, --allow-workspace
Allow the specification of a workspace (instead of a
project) directory as the destination path.
--force Ignore all warnings, just synchronize.
-m, --merge Clone all the jobs that are not present in destination
from source.
--parallel [PARALLEL]
Use multiple threads for synchronization.You may
optionally specify how many threads to use, otherwise
all available processing units will be utilized.
--stats Provide file transfer statistics.
-H, --human-readable Provide statistics with human readable formatting.
--json Print statistics in JSON formatting.
copy options:
-a, --archive archive mode; equivalent to: '-rltpog'
-r, --recursive Do not skip sub-directories, but synchronize
recursively.
-l, --links Copy symbolic links as symbolic links pointing to the
original source.
-p, --perms Preserve permissions.
-o, --owner Preserve owner.
-g, --group Preserve group.
-t, --times Preserve file modification times (requires -p).
-x [EXCLUDE], --exclude [EXCLUDE]
Exclude all files matching the given pattern. Exclude
all files if this option is provided without any
argument.
-I, --ignore-times Never rely on file meta data such as the size or the
modification time when determining file differences.
--size-only Ignore modification times during file comparison.
Useful when synchronizing between file systems with
different timestamp resolution.
--round-times Round modification times during file comparison.
Useful when synchronizing between file systems with
different timestamp resolution.
-n, --dry-run Do not actually execute the synchronization. Increase
the output verbosity to see messages about what would
potentially happen.
-u, --update Skip files with newer modification time stamp.This is
a short-cut for: --strategy=update.
sync strategy:
-s {always,never,update,Ask}, --strategy {always,never,update,Ask}
Specify a synchronization strategy, for differing
files.
-k KEY, --key KEY Specify a regular expression for keys that should be
overwritten as part of the project and job document
synchronization.
--all-keys Overwrite all conflicting keys. Equivalent to
`--key='.*'`.
--no-keys Never overwrite any conflicting keys.
select:
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Only synchronize jobs that match the state point
filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Only synchronize jobs that match the document filter.
-j JOB_ID [JOB_ID ...], --job-id JOB_ID [JOB_ID ...]
Only synchronize jobs with the given job ids.
import¶
usage: signac import [-h] [--move] [--sync] [--sync-interactive]
[origin] [schema_path]
Import an existing dataset into this project. Optionally provide a file path
based schema to specify the state point metadata. Providing a path based
schema is only necessary if the data set was not previously exported from a
signac project.
positional arguments:
origin The origin to import from. May be a path to a directory,
a zipfile, or a tarball. Defaults to the current working
directory.
schema_path Specify an optional import path, such as
'foo/{foo:int}'. Possible type definitions include bool,
int, float, and str. The type is assumed to be 'str' if
no type is specified.
optional arguments:
-h, --help show this help message and exit
--move Move the data upon import instead of copying. Can only
be used when importing from a directory.
--sync Attempt recursive synchronization with default
arguments.
--sync-interactive Synchronize the project with the origin data space
interactively.
export¶
usage: signac export [-h] [--move] [-f FILTER [FILTER ...]]
[-d DOC_FILTER [DOC_FILTER ...]] [-j JOB_ID [JOB_ID ...]]
target [schema_path]
Export the project data space (or a subset) to a directory, a zipfile, or a
tarball.
positional arguments:
target The target to export to. May be a path to a directory,
a zipfile, or a tarball.
schema_path Specify an optional export path, based on the job
state point, e.g., 'foo/{job.sp.foo}'.
optional arguments:
-h, --help show this help message and exit
--move Move data to export target instead of copying. Can
only be used when exporting to a directory target.
select:
-f FILTER [FILTER ...], --filter FILTER [FILTER ...]
Limit the jobs to export to those matching the state
point filter.
-d DOC_FILTER [DOC_FILTER ...], --doc-filter DOC_FILTER [DOC_FILTER ...]
Limit the jobs to export to those matching this
document filter.
-j JOB_ID [JOB_ID ...], --job-id JOB_ID [JOB_ID ...]
Limit the jobs to export to those matching the
provided job ids.
config¶
usage: signac config [-h] [-g] [-l] [-f] {show,set,host,verify} ...
positional arguments:
{show,set,host,verify}
optional arguments:
-h, --help show this help message and exit
-g, --global Modify the global configuration.
-l, --local Modify the local configuration.
-f, --force Skip sanity checks when modifying the configuration.