taucmdr.model.trial module

Trial data model.

Every application of an Experiment produces a new Trial. The trial record completely describes the hardware and software environment that produced the performance data.

class taucmdr.model.trial.Trial(record)

Bases: Model

Trial data model.

_attributes = {'begin_time': {'description': 'date and time the trial began', 'type': 'datetime'}, 'command': {'description': 'command line executed when performing the trial', 'required': True, 'type': 'string'}, 'cwd': {'description': 'directory the trial was performed in', 'required': True, 'type': 'string'}, 'data_size': {'description': 'the size in bytes of the trial data', 'type': 'integer'}, 'description': {'argparse': {'flags': ('--description',), 'metavar': '<text>'}, 'description': 'description of this trial', 'type': 'string'}, 'elapsed': {'description': 'seconds spent executing the application command only (excludes all other operations)', 'type': 'float'}, 'end_time': {'description': 'date and time the trial ended', 'type': 'datetime'}, 'environment': {'description': 'shell environment in which the trial was performed, encoded as a base64 string', 'type': 'string'}, 'experiment': {'description': "this trial's experiment", 'model': <class 'taucmdr.model.experiment.Experiment'>, 'required': True}, 'number': {'description': 'trial number', 'primary_key': True, 'required': True, 'type': 'integer'}, 'output': {'description': 'stdout and stderr of program', 'type': 'string'}, 'phase': {'description': 'phase of trial: initializing, executing, complete, or failed', 'type': 'string'}, 'return_code': {'description': 'return code of the command executed when performing the trial', 'type': 'integer'}}

_key_attribute = 'number'

_postprocess_slog2()

classmethod _separate_launcher_cmd(cmd)

Separate the launcher command and it’s arguments from the application command(s) and arguments.

Parameters:

cmd (list) – Command line.

Returns:

(Launcher command, Remainder of command line)

Return type:

tuple

Raises:

ConfigurationError – No application config files or executables found after a recognized launcher command.

associations = {'experiment': (<class 'taucmdr.model.experiment.Experiment'>, 'trials')}

(Controller, str) tuples keyed by attribute name defining attribute associations.

attributes = {'begin_time': {'description': 'date and time the trial began', 'type': 'datetime'}, 'command': {'description': 'command line executed when performing the trial', 'required': True, 'type': 'string'}, 'cwd': {'description': 'directory the trial was performed in', 'required': True, 'type': 'string'}, 'data_size': {'description': 'the size in bytes of the trial data', 'type': 'integer'}, 'description': {'argparse': {'flags': ('--description',), 'metavar': '<text>'}, 'description': 'description of this trial', 'type': 'string'}, 'elapsed': {'description': 'seconds spent executing the application command only (excludes all other operations)', 'type': 'float'}, 'end_time': {'description': 'date and time the trial ended', 'type': 'datetime'}, 'environment': {'description': 'shell environment in which the trial was performed, encoded as a base64 string', 'type': 'string'}, 'experiment': {'description': "this trial's experiment", 'model': <class 'taucmdr.model.experiment.Experiment'>, 'required': True}, 'number': {'description': 'trial number', 'primary_key': True, 'required': True, 'type': 'integer'}, 'output': {'description': 'stdout and stderr of program', 'type': 'string'}, 'phase': {'description': 'phase of trial: initializing, executing, complete, or failed', 'type': 'string'}, 'return_code': {'description': 'return code of the command executed when performing the trial', 'type': 'integer'}}

Model attributes.

execute_command(expr, cmd, cwd, env, record_output=False)

Execute a command as part of an experiment trial.

Creates a new subprocess for the command and checks for TAU data files when the subprocess exits.

Parameters:

• expr (Experiment) – Experiment data.

• cmd (str) – Command to profile, with command line arguments.

• cwd (str) – Working directory to perform trial in.

• env (dict) – Environment variables to set before performing the trial.

Returns:

Subprocess return code.

Return type:

int

export(dest)

Export experiment trial data.

Parameters:

dest (str) – Path to directory to contain exported data.

Raises:

ConfigurationError – This trial has no data.

get_data_files()

Return paths to the trial’s data files or directories mapped by data type.

Post-process trial data if necessary and return a dictionary mapping the types of data produced by this trial to paths to related data files or directories. The paths should be suitable for passing on a command line to one of the known data analysis tools. For example, a trial producing SLOG2 traces and TAU profiles would return {"slog2": "/path/to/tau.slog2", "tau": "/path/to/directory/"}.

Returns:

Keys are strings indicating the data type; values are filesystem paths.

Return type:

dict

key_attribute = 'number'

Name of an attribute that serves as a unique identifier.

name = 'Trial'

Name of the model.

on_create()

Callback to be invoked after a new data record is created.

on_delete()

Callback to be invoked before a data record is deleted.

on_update(changes)

Callback to be invoked after a data record is updated.

classmethod parse_launcher_cmd(cmd)

Parses a command line to split the launcher command and application commands.

Parameters:

cmd (list) – Command line.

Returns:

(Launcher command, possibly empty list of application commands).

Return type:

tuple

property prefix

references = {}

(Controller, str) tuples listing foreign models referencing this model.

class taucmdr.model.trial.TrialController(model_cls, storage, context=None)

Bases: Controller

Trial data controller.

static _mark_time(mark, expr)

_perform_interactive(expr, trial, cmd, cwd, env, record_output=False)

perform(proj, cmd, cwd, env, description, record_output=False)

Performs a trial of an experiment.

Parameters:

• expr (Experiment) – Experiment data.

• proj (Project) – Project data.

• cmd (str) – Command to profile, with command line arguments.

• cwd (str) – Working directory to perform trial in.

• env (dict) – Environment variables to set before performing the trial.

• description (str) – Description of this trial.

renumber(old_trials, new_trials)

Renumbers trial id of an experiment.

Parameters:

• old_trials (list) – old trial numbers.

• new_trials (list) – new trial numbers.

exception taucmdr.model.trial.TrialError(value, *hints)

Bases: ConfigurationError

Indicates there was an error while performing an experiment trial.

message_fmt = "%(value)s\n\n%(hints)s\nPlease check the selected configuration for errors or send '%(logfile)s' to  %(contact)s for assistance."

Format string for the error message.

taucmdr.model.trial.attributes()