`seisflows.system.singularity`

A Cluster-adjacent base class that provides core utilities for interactions with HPC systems running Singularity. Must be overloaded by subclasses defined for specific workload managers / clusters.

The Singularity class was written for clusters running SeisFlows through Docker containers using Singularity. The reason for writing a separate class is because Docker containers do not have access to the workload manager (e.,g SLURM/sbatch) and therefore we cannot run job submission calls directly from the Python environment. Instead, each time a job must be submitted to the Cluster, the User must manually submit.

Note

To users looking to run SeisFlows directly via their Cluster Conda environment, look at the Cluster class and its workload manager-specific sub-classes

Module Contents

Classes

Singularity

Singularity System

class seisflows.system.singularity.Singularity(title=None, mpiexec='', ntask_max=None, tasktime=1, environs='', singularity_exec='singularity', path_container=None, **kwargs)

Bases: seisflows.system.workstation.Workstation

Singularity System

HPC interfacing through Docker/Singularity containers

Parameters

type title: str
param title: The name used to submit jobs to the system, defaults to the name of the current working directory
type mpiexec: str
param mpiexec: Function used to invoke executables on the system. For example ‘mpirun’, ‘mpiexec’, ‘srun’, ‘ibrun’
type ntask_max: int
param ntask_max: limit the number of concurrent tasks in a given array job
type tasktime: float
param tasktime: maximum job time in minutes for each job spawned by the SeisFlows master job during a workflow. These include, e.g., running the forward solver, adjoint solver, smoother, kernel combiner. All spawned tasks receive the same task time. Fractions of minutes acceptable.
type environs: str
param environs: Optional environment variables to be provided in the following format VAR1=var1,VAR2=var2… Will be set using os.environs

Paths

type path_container: str
param path_container: path to the Docker Image that contains adjTomo software package

***

property run_call_header

The run call defines the Singularity wrapper which executes run calls using the Docker image. It also binds the current working directory inside the container so that we can write back to the local filesystem.

Note

Generalized cluster returns empty string but child system classes will need to overwrite the submit call.

Return type: str
Returns: the system-dependent portion of a run call

__doc__

setup(): Copies ‘submit’ and ‘run’ .py scripts from the repository into the working directory so that the User can run these scripts directly. This is a manual step in order to allow Users to run with a container without using native environment commands (e.g., sbatch) from inside a container.

submit(workdir=None, parameter_file='parameters.yaml')

Submits the main workflow job as a serial job submitted directly to the system that is running the master job

Parameters

workdir (str) – path to the current working directory
parameter_file (str) – parameter file name used to instantiate the SeisFlows package

run(funcs, single=False, **kwargs)

Runs tasks multiple times in parallel by submitting NTASK new jobs to system. The list of functions and its kwargs are saved as pickles files, and then re-loaded by each submitted process with specific environment variables. Each spawned process will run the list of functions.