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, *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

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, stdout=None, stderr=None, *args, **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)

Register a command to be executed.

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