Quickstart¶
This project is based on the basic workflow implemented in the signac tutorial. Being familiar with the tutorial will help in understanding the logic of this template.
The project requires the signac-flow package, which implements the core logic of the example workflow within a flow.FlowProject
class.
In addition it adds functionality to work with schedulers in a cluster environment.
The Basics¶
This is a list of key things you need to know in order to efficiently work with this project:
- All modules are part of the
my_project
package located in the directory of the same name.- The project execution logic is implemented within the
project.MyProject
class.- All jobs are classified via
str
-labels with theMyProject.classify()
method.- The next operation is identified via the
MyProject.next_operation()
method.- The project status may be examined by executing the
status
module.- Job-operations may be submitted to a scheduler via the
submit
module.- Python-based operations are implemented within the
scripts/operations.py
module.- Operations defined in the
scripts/operations.py
module can be executed directly via thescripts/run.py
script.
A complete overview of all modules and functions an be found in the API chapter.
Step-by-step¶
This is a description on how to execute the complete workflow of this project.
Initialize the data space using a random number or string, e.g. your username:
$ python -m my_project.init $USER # (or $ python my_project.init 42)
You can check the status of your project:
$ python -m my_project.status -d
Query scheduler...
Determine job stati...
Generate output...
Status project 'MyProject':
Total # of jobs: 10
label progress
------- ----------
Detailed view:
job_id S next_op labels
-------------------------------- --- ---------- --------
6c57f630f0b62d449349ee2322cc16b6 U ! initialize
e0cf9aa968b48b22c66bbfda41d46129 U ! initialize
1677c153f81290d2e6e8b97a4f1d4297 U ! initialize
a230567b8a54d5c44d88b806b390b426 U ! initialize
3904431a51a3d3e4a31358f24b69d43f U ! initialize
...
Abbreviations used:
!: requires_attention
S: status
U: unknown
We initialize the jobs for hoomd-blue:
$ python scripts/run.py initialize
Notice that the next_op and labels have changed if you check the status again:
$ python -m my_project.status -d
Query scheduler...
Determine job stati...
Generate output...
Status project 'MyProject':
Total # of jobs: 10
label progress
----------- --------------------------------------------------
initialized |########################################| 100.00%
Detailed view:
job_id S next_op labels
-------------------------------- --- --------- -----------
6c57f630f0b62d449349ee2322cc16b6 U ! estimate initialized
e0cf9aa968b48b22c66bbfda41d46129 U ! estimate initialized
1677c153f81290d2e6e8b97a4f1d4297 U ! estimate initialized
a230567b8a54d5c44d88b806b390b426 U ! estimate initialized
3904431a51a3d3e4a31358f24b69d43f U ! estimate initialized
...
Abbreviations used:
!: requires_attention
S: status
U: unknown
Compute the ideal gas estimate, just like in the tutorial:
$ python scripts/run.py estimate
Execute a molecular dynamics simulation using hoomd-blue with:
$ python scripts/run.py sample 6c57
where 6c57 is the first few characters of the job id.
Note
When no job id is provided as argument, the specified operation is executed for all jobs.
Instead of running the operations directly, we can also submit them to a scheduler:
$ python -m my_project.submit -j sample
In this case we explicitly specified which operation to submit. If we omit the argument, the next operation for each job will be submitted.
Tip
Use the --pretend
argument to print the submission script to the screen instead
of submitting it during debugging.
The scheduler is determined from the environment with the environment
module.
If your environment does not have a scheduler or it is not configured, signac-flow will raise an exception.
However, you can use a test environment with --test
argument, which will mock an
actual submission process.