==============================
``grail.data.multirun`` Module
==============================
.. include:: ..\..\version.h

.. contents:: Table of Contents
   :backlinks: top


--------
Overview
--------

This module provides the ability to obtain information about Multirun packages and responses,  
and change variable values in a particular response set.  

The procedures in a Multirun are stored in a Package. The parameters which vary in a package 
are stored in a Response set. There can be several Response sets per Package.

--------
Examples
--------

The following snippet illustrates how to read a varaible value from a multirun:

.. Python::
        mr = multirun.Multirun('project_path')		#create a Multirun instance
        pkg = mr.getPackage('package_name')		#create a Package instance
        res = pkg.getResponse('response_name')		#create a Response instance
        val = res.getVariableValue("?01", 1)
	print val


The following snippet illustrates how to write a values to a varaible:

.. Python::
        mr = multirun.Multirun('project_path')		#create a Multirun instance
        pkg = mr.getPackage('package_name')		#create a Package instance
        res = pkg.getResponse('response_name')		#create a Response instance
        res.setVariableValue("?01", 1, "new_value")
        res.setVariableValue("?02", 1, "next_value")


--------
Multirun
--------

:c:`Multirun(project_path)`

   Multirun is the top-level class.  The constructor takes the prj file path as it's only argument.  A Multirun can contain multiple Packages.

   **Methods**

      :df:`getPackageCount()`
	 Returns the number of packages in the multirun.

      :df:`getPackageNames()`
         Returns a list of package names.

      :df:`getPackage(package_name)`
	 Returns a reference to a  :c:`Package` object (see below).

      :df:`execute(package_name, response_name)`
	 Runs the multirun (from the command line) using the given package and response.

   **Attributes**

      :dd:`project`
         This is the path to the project file.
      

--------
Package
--------

:c:`Package`

   Package is an inner-class of Multirun (you must create an instance of a Multirun before you 
   can create a Package object). A Package can contain multiple Responses.

   **Methods**

      :df:`getProcedureNames()`
         Returns a list of procedures in the package.

      :df:`getResponseCount()`
	 Returns the number of response sets in the package.
                
      :df:`getResponseNames()`
         Returns a list of response set names in the package.

      :df:`getResponse(response_name)`
         Returns a reference to a  :c:`Response` object (see below).

   **Attributes**

      :dd:`name`
         This is the name of the package.
      

--------
Response
--------

:c:`Response`

   Response is an inner-class of Package (you must create an instance of a Package before you 
   can create a Response object).

   **Methods**

      :df:`getVariableCount()`
         Returns the number of variables in the response set.

      :df:`getVariableNames()`
         Returns a list of variable names in the response set.

      :df:`getRunCount()`
	 Return the number of runs (the number of possible values for the variable).

      :df:`getVariableValue(variable, runID)`
         Return the value of the variable for the given run number. Run numbers begin at 1.

      :df:`setVariableValue(variable, runID, value)`
         Change the value of the variable for the given run number. Run numbers begin at 1. A :e:`TypeError` will be raised of the value is not of type String.

   **Attributes**

      :dd:`name`
         This is the name of the response set.