`carputils.job`.Job

class carputils.job.Job(ID)

A sequence of commands plus the tools to execute them.

A job defines a series of commands that can be executed in different ways. Each job has an ID, which defines where the output of its commands is placed, plus a series of commands that can either be run immediately as they are registered or delayed for later execution in different ways.

A job is instantiated with its ID:

>>> job = Job('2015-11-25_important_sim')

and its ID can then be accessed as an attribute:

>>> print job.ID
2015-11-25_important_sim

Commands are then registered for the job with the register() method:

>>> from carputils.job.command import ShellCommand
>>> job.register(ShellCommand(['ls', '-l'], 'List directory'))

however, for convenience, a number of methods such as bash() are provided to avoid the need to construct your own commands manually:

>>> job.bash(['ls', '-l'])

On a normal system, commands are executed immeditately once registered (unless the ‘delayed’ keyword argument is set to True), however on batch systems, commands are stored. The script() method may then be used to generate a bash script executing the stored commands.

The submit() method may also be used to automatically generate and submit the job on HPC systems, using the carputils platform.

>>> job.submit()

Users will generally only need to use the convenience submission methods, as the job creation and batch script generation and submission is done automatically by the carputils framework.

Args:

ID : str: The identifier for this job, both the name of the output directory and the identifier on batch systems

bash(cmd, message=None, delayed=False, *args, **kwargs)

Execute an arbitrary command in the shell.

Args:

cmd : list: Command to be executed
message : str, optional: Descriptive message to display when running command

bench(cmd, simname=None, msg=None, *args, **kwargs)

Execute a BENCH simulation.

Runs a BENCH sim with mpiexec, automatically adding the number of processes and command configuration.

Args:

cmd : list: The command to be executed with MPI
simname : str, optional: Name to display when running command, defaults to job ID

carp(cmd, simname=None, polling_subdirs=True, *args, **kwargs)

Execute an openCARP simulation.

Runs an openCARP sim with mpiexec, automatically adding the number of processes and debugger/profiler options from the current run configuration.

Args:

cmd : list: The command to be executed with MPI
simname : str, optional: Name to display when running command, defaults to job ID

cp(path_from, path_to, cpdir=False, *args, **kwargs)

Copy a file.

Args:

path_from : str: Path of file to copy
path_to : str: Path to copy file to

cvstool(cmd, stdout=None, stderr=None, *args, **kwargs)

Execute cvstool

Args:

cmd : list: The command to be executed with cvstool

gunzip(filename, *args, **kwargs)

Unzip a .gz file.

Args:

filename : str: Path of file to unzip

link(target, link_name=None, *args, **kwargs)

Make a symbolic link.

Args:

target : str: Target of link (first arg to ‘ln -s’)
link_name : str, optional: Place to put link (second arg to ‘ln -s’)

meshalyzer(geom, *args, **kwargs)

Run meshalyzer.

Args:

geom: str

Basename of mesh to visualise

args: str

Additional data/display config files to pass as command line arguments to meshalyzer

kwargs:

compsurf: bool, optional: If True, generate a surface on the fly (default: False)
monitor: int: Delay in seconds before spawning visualization process after job launched (default: none) Return the spawned process.

meshtool(cmd, *args, stdout=None, stderr=None, **kwargs)

Execute meshtool

Args:

cmd : list: The command to be executed with meshtool

mkdir(directory, parents=False, *args, **kwargs)

Make a directory.

Args:

directory : str: Path of directory to make
parents : bool, optional: True to automatically generate parents (mkdir -p)

mpi(cmd, message='Executing MPI Command', *args, **kwargs)

Execute a command with MPI.

Runs a command with mpiexec, automatically adding the number of processes and debugger/profiler options from the current run configuration.

Args:

cmd : list: The command to be executed with MPI
message : str, optional: Descriptive message to display when running command

mv(path_from, path_to, *args, **kwargs)

Move a file.

Args:

path_from : str: Path of file to move
path_to : str: Path to move file to

python(cmd, *args, **kwargs)

Execute a python script.

# FIXME: update documentation Runs a pythonCARP sim with mpiexec, automatically adding the number of processes and debugger/profiler options from the current run configuration.

Args:

cmd : callable: The function to be executed with python

register(command, delayed=False)

Args:

command : carputils.job.command.Command: The command object
delayed : bool, optional: If True, never execute immediately - instead wait until first non- delayed command before processing the whole series

rm(filename, rmdir=False, *args, **kwargs)

Remove a file or a directory

Args:

filename : str: Path of file to remove
rmdir : str: Set to True if removing directory

script()

Generate a bash script running the command sequence

Returns:

str: The content of the batch script

submit(argv=None)

Submit the command sequence to the batch system.

Args:

argv : list, optional: If provided, include the command line in the generated script, for providence