taucmdr.model.experiment module

Experiment data model.

An Experiment uniquely groups a Target, Application, and Measurement and will have zero or more Trial. There is one selected experiment per project. The selected experiment will be used for application compilation and trial visualization.

class taucmdr.model.experiment.Experiment(record)

Bases: Model

Experiment data model.

_attributes = {'application': {'argparse': {'flags': ('--application',), 'metavar': '<name>'}, 'description': 'Application this experiment uses', 'model': <class 'taucmdr.model.application.Application'>, 'required': True}, 'measurement': {'argparse': {'flags': ('--measurement',), 'metavar': '<name>'}, 'description': 'Measurement parameters for this experiment', 'model': <class 'taucmdr.model.measurement.Measurement'>, 'required': True}, 'name': {'description': 'human-readable experiment name', 'primary_key': True, 'type': 'string', 'unique': True}, 'project': {'description': 'Project this experiment belongs to', 'model': <class 'taucmdr.model.project.Project'>, 'required': True, 'unique': True}, 'record_output': {'argparse': {'flags': ('--record-output',)}, 'default': False, 'description': 'Record application stdout', 'type': 'boolean'}, 'target': {'argparse': {'flags': ('--target',), 'metavar': '<name>'}, 'description': "The experiment's hardware/software configuration", 'model': <class 'taucmdr.model.target.Target'>, 'required': True}, 'tau_makefile': {'description': 'TAU Makefile used during this experiment, if any.', 'type': 'string'}, 'trials': {'collection': <class 'taucmdr.model.trial.Trial'>, 'description': 'Trials of this experiment', 'via': 'experiment'}}

_configure()

_key_attribute = 'name'

associations = {'project': (<class 'taucmdr.model.project.Project'>, 'experiments'), 'trials': (<class 'taucmdr.model.trial.Trial'>, 'experiment')}

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

attributes = {'application': {'argparse': {'flags': ('--application',), 'metavar': '<name>'}, 'description': 'Application this experiment uses', 'model': <class 'taucmdr.model.application.Application'>, 'required': True}, 'measurement': {'argparse': {'flags': ('--measurement',), 'metavar': '<name>'}, 'description': 'Measurement parameters for this experiment', 'model': <class 'taucmdr.model.measurement.Measurement'>, 'required': True}, 'name': {'description': 'human-readable experiment name', 'primary_key': True, 'type': 'string', 'unique': True}, 'project': {'description': 'Project this experiment belongs to', 'model': <class 'taucmdr.model.project.Project'>, 'required': True, 'unique': True}, 'record_output': {'argparse': {'flags': ('--record-output',)}, 'default': False, 'description': 'Record application stdout', 'type': 'boolean'}, 'target': {'argparse': {'flags': ('--target',), 'metavar': '<name>'}, 'description': "The experiment's hardware/software configuration", 'model': <class 'taucmdr.model.target.Target'>, 'required': True}, 'tau_makefile': {'description': 'TAU Makefile used during this experiment, if any.', 'type': 'string'}, 'trials': {'collection': <class 'taucmdr.model.trial.Trial'>, 'description': 'Trials of this experiment', 'via': 'experiment'}}

Model attributes.

configure()

Sets up the Experiment for a new trial.

Installs or configures TAU and all its dependencies. After calling this function, the experiment is ready to operate on the user’s application.

Returns:

Object handle for the TAU installation.

Return type:

TauInstallation

classmethod controller(storage=<taucmdr.cf.storage.storage_dispatch.ProjectStorageDispatch object>)

data_size()

key_attribute = 'name'

Name of an attribute that serves as a unique identifier.

managed_build(compiler_cmd, compiler_args)

Uses this experiment to perform a build operation.

Checks that this experiment is compatible with the desired build operation, prepares the experiment, and performs the operation.

Parameters:

• compiler_cmd (str) – The compiler command intercepted by TAU Commander.

• compiler_args (list) – Compiler command line arguments intercepted by TAU Commander.

Raises:

ConfigurationError – The experiment is not configured to perform the desired build.

Returns:

Build subprocess return code.

Return type:

int

managed_rewrite(rewrite_package, executable, inst_file)

Instrument an executable via binary rewriting using the experiment’s configuration.

Builds a TauInstallation from the experiment’s target, application, and measurement settings, then delegates to TauInstallation.rewrite().

Parameters:

• rewrite_package (str) – Rewriting backend (‘dyninst’, ‘pebil’, or ‘maqao’).

• executable (str) – Path to the executable to instrument.

• inst_file (str) – Path for the instrumented output file.

managed_run(launcher_cmd, application_cmds, description=None)

Uses this experiment to run an application command.

Performs all relevant system preparation tasks to run the user’s application under the specified experimental configuration.

Parameters:

• launcher_cmd (list) – Application launcher with command line arguments.

• application_cmds (list) – List of application executables with command line arguments (list of lists).

• description (str) – If not None, a description of the run.

Raises:

ConfigurationError – The experiment is not configured to perform the desired run.

Returns:

Application subprocess return code.

Return type:

int

name = 'Experiment'

Name of the model.

next_trial_number()

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.

property prefix

classmethod rebuild_required()

Builds a string indicating if an application rebuild is required.

Rebuild information is taken from the ‘rebuild_required’ topic.

Returns:

String indicating why an application rebuild is required.

Return type:

str

references = {(<class 'taucmdr.model.project.Project'>, 'experiment'), (<class 'taucmdr.model.trial.Trial'>, 'experiment')}

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

classmethod select(name)

Changes the selected experiment in the current project.

Raises:

ExperimentSelectionError – No experiment with the given name in the currently selected project.

Parameters:

name (str) – Name of the experiment to select.

trials(trial_numbers=None)

Get a list of modeled trial records.

If bool(trial_numbers) is False, return the most recent trial. Otherwise return a list of Trial objects for the given trial numbers.

Parameters:

trial_numbers (list) – List of numbers of trials to retrieve.

Returns:

Modeled trial records.

Return type:

list

Raises:

ConfigurationError – Invalid trial number or no trials in selected experiment.

verify()

Checks all components of the experiment for mutual compatibility.

class taucmdr.model.experiment.ExperimentController(model_cls, storage, context=None)

Bases: Controller

Experiment data controller.

_check_unique(data, match_any=False)

Default match_any to False to prevent matches outside the selected project.

all(context=True)

count()

Return the number of records.

Returns:

Effectively len(self.all())

Return type:

int

delete(keys)

Delete recorded data and update associations.

The behavior depends on the type of keys:

• Record.ElementIdentifier: delete the record with that element identifier.

• dict: delete all records with attributes matching keys.

• list or tuple: delete all records matching the elements of keys.

• bool(keys) == False: raise ValueError.

Invokes the on_delete callback after the data is deleted. If this callback raises an exception then the operation is reverted.

Parameters:

• keys (dict) – Attributes to match.

• keys – Fields or element identifiers to match.

exists(keys)

Check if a record exists.

Parameters:

keys – See AbstractStorage.contains.

Returns:

True if a record matching keys exists, False otherwise.

Return type:

bool

one(keys, context=True)

search(keys=None, context=True)

taucmdr.model.experiment.attributes()