CellMLToNektar.translators Namespace Reference

Classes
class	CellMLTranslator
class	ConfigurationError
class	ConfigurationStore
class	SolverInfo
class	TranslationError

Functions
def	version_comment (note_time=True)
def	debugexpr (e)
def	get_options (args, default_options=None)
def	load_model (model_file, options)
def	run ()

Variables
list	__version__ = "$Revision: 25950 $"[11:-2]

Function Documentation

debugexpr()

def CellMLToNektar.translators.debugexpr

(

e

)

Definition at line 74 of file translators.py.

def debugexpr(e):
    "For debugging."
    v = None
    if isinstance(e, cellml_variable):
        v = e
    elif isinstance(e, mathml_apply):
        v = e.assigned_variable()
    if v:
        r = (v==e, v.name, v.get_usage_count())
    else:
        r = (False, '', -1)
    return r
 
 

get_options()

def CellMLToNektar.translators.get_options	(		args,
			default_options = None
	)

get_options(args):
Process our command-line options.

args is a list of options & positional arguments.

default_options, if given, is an instance of optparse.Values created by a
previous call to this function.

Definition at line 2489 of file translators.py.

def get_options(args, default_options=None):
    """get_options(args):
    Process our command-line options.
 
    args is a list of options & positional arguments.
    
    default_options, if given, is an instance of optparse.Values created by a
    previous call to this function.
    """
    usage = 'usage: %prog [options] <cellml file or URI>'
    parser = optparse.OptionParser(version="%%prog %s" % __version__,
                                   usage=usage)
    parser.add_option('-q', '--quiet', action='store_true', default=False,
                      help="don't show warning messages, only errors")
    # What type of translation is being performed
    parser.add_option('-T', '--translate',
                      dest='translate', action='store_true',
                      default=True,
                      help="output computer code [default]")
    parser.add_option('-C', '--output-cellml',
                      dest='translate', action='store_false',
                      help="output an annotated CellML file instead of translating, on stdout unless -o specified")
    translators = sorted(CellMLTranslator.translators)
    parser.add_option('-t', '--translate-type',
                      type='choice', choices=translators,
                      default='Nektar', metavar='TYPE',
                      help="the type of code to output [default: %default].  "
                      "Choices: " + str(translators))
    parser.add_option('-o', dest='outfilename', metavar='OUTFILE',
                      help="write program code to OUTFILE [default action is to use the input filename with a different extension]")
    # Global adjustment settings
    parser.add_option('--config-file',
                      action='append', default=[],
                      help="pathname of configuration file")
    parser.add_option('-A', '--fully-automatic',
                      action='store_true', default=False,
                      help="if human intervention is required, fail noisily")
    parser.add_option('--assume-valid',
                      action='store_true', default=False,
                      help="skip some of the model validation checks")
    parser.add_option('--warn-on-unit-conversions',
                      action='store_true', default=False,
                      help="generate a warning if unit conversions are required")
    parser.add_option('--Wu', '--warn-on-units-errors',
                      action='store_true', default=False,
                      dest='warn_on_units_errors',
                      help="give a warning instead of an error for dimensional inconsistencies")
    parser.add_option('-V', '--transmembrane-potential', default=None, metavar='POT_VAR',
                      help="POT_VAR is the full name of the variable representing the transmembrane potential."
                      "  If not specified here, the configuration file will be used, which is the prefered method."
                      "  Defaults to 'membrane,V'.")
    parser.add_option('-d', '--debug', action='store_true', default=False,
                      help="output debug info to stderr")
    parser.add_option('-D', '--debug-source', action='append',
                      help="only show debug info from the specified part of the code."
                      "  This option may appear more than once to select multiple sources.  Implies -d.")
    parser.add_option('--profile', action='store_true', default=False,
                      help="turn on profiling of PyCml")
    # To examine the profile do something like:
    #    import os,pstats
    #    os.chdir('/tmp')
    #    files = filter(lambda f: f.startswith('pycml'), os.listdir('.'))
    #    p = pstats.Stats(*files)
    #    p.strip_dirs().sort_stats('cum').print_stats(15)
    # What optimisations/transformations to do
    group = optparse.OptionGroup(parser, 'Transformations',
                                 "These options control which transformations (typically optimisations) are applied in the generated code")
    group.add_option('-l', '--lookup-tables',
                     dest='lut', action='store_true', default=False,
                     help="perform a lookup table analysis")
    group.add_option('-p', '--pe', '--partial-evaluation',
                     dest='pe', action='store_true', default=False,
                     help="partially evaluate the model")
    group.add_option('-u', '--units-conversions',
                     action='store_true', default=False,
                     help="add explicit units conversion mathematics")
    group.add_option('-j', '--maple-output',
                     metavar='FILENAME', default=None,
                     help="file containing output from a Maple script generated using -J.  The generated"
                     " code/CellML will then contain a symbolic Jacobian as computed by Maple.")
    group.add_option('-J', '--do-jacobian-analysis',
                     action='store_true', default=False,
                     help="generate code to perform Jacobian analysis for backward Euler & CVODE; implies -t Maple")
    group.add_option('--backward-euler',
                     action='store_true', default=False,
                     help="generate a specialised cell model that solves itself using a decoupled"
                     " backward Euler method.  Not compatible with --rush-larsen.  Implies -t Chaste."
                     "  Requires -j.")
    group.add_option('--rush-larsen',
                     action='store_true', default=False,
                     help="use the Rush-Larsen method to solve Hodgkin-Huxley style gating variable"
                     " equations.  Not compatible with --backward-euler.  Implies -t Chaste.")
    group.add_option('--grl1',
                     action='store_true', default=False,
                     help="use the GRL1 method to solve Hodgkin-Huxley style gating variable"
                     " equations.  Not compatible with the backward Euler transformation."
                     " Implies -t Chaste.")
    group.add_option('--grl2',
                     action='store_true', default=False,
                     help="use the GRL2 method to solve Hodgkin-Huxley style gating variable"
                     " equations.  Not compatible with the backward Euler transformation."
                     " Implies -t Chaste.")
    parser.add_option_group(group)
    # Settings tweaking the generated code
    group = optparse.OptionGroup(parser, 'Generated code options')
    group.add_option('-c', '--class-name', default=None,
                     help="explicitly set the name of the generated class")
    group.add_option('-a', '--augment-class-name',
                     dest='augment_class_name', action='store_true',
                     default=False,
                     help="alter the class name to show what transformations are used")
    group.add_option('--no-timestamp',
                     action='store_true', default=False,
                     help="don't add a timestamp comment to generated files")
    parser.add_option_group(group)
    # Options specific to Maple output
    group = optparse.OptionGroup(parser, 'Maple options', "Options specific to Maple code output")
    group.add_option('--dont-omit-constants',
                     dest='omit_constants', action='store_false', default=True,
                     help="when generating Maple code, include assignments of constants")
    group.add_option('--compute-partial-jacobian', dest='compute_full_jacobian',
                     action='store_false', default=True,
                     help="make generated Maple code compute a Jacobian specific to a Newton solve"
                     " of the nonlinear portion of the ODE system, rather than the full system Jacobian")
    parser.add_option_group(group)
    # Options specific to Python output
    group = optparse.OptionGroup(parser, 'Python options', "Options specific to Python code output")
    group.add_option('--no-numba', dest='numba', default=True, action='store_false',
                     help="turn off using Numba to optimise code on-the-fly")
    parser.add_option_group(group)
    # Options specific to Chaste output
    group = optparse.OptionGroup(parser, 'Chaste options', "Options specific to Chaste code output")
    group.add_option('-y', '--dll', '--dynamically-loadable',
                     dest='dynamically_loadable',
                     action='store_true', default=False,
                     help="add code to allow the model to be compiled to a shared library and dynamically loaded"
                     " (only works if -t Chaste is used)")
    group.add_option('--use-chaste-stimulus',
                     action='store_true', default=False,
                     help="when generating Chaste code, use Chaste's stimulus rather than that defined in the model")
    group.add_option('--no-use-chaste-stimulus', dest='use_chaste_stimulus',
                     action='store_false',
                     help="when generating Chaste code, use the model's stimulus, not Chaste's")
    group.add_option('-i', '--convert-interfaces',
                     action='store_true', default=False,
                     help="perform units conversions at interfaces to Chaste (only works if -t Chaste is used)")
    group.add_option('--use-i-ionic-regexp', dest='use_i_ionic_regexp',
                     action='store_true', default=False,
                     help="determine ionic currents from the regexp specified in the config file"
                     " rather than analysing the voltage derivative equation")
    group.add_option('--include-dt-in-tables',
                     action='store_true', default=False,
                     help="[experimental] allow timestep to be included in lookup tables.  By default"
                     " uses the timestep of the first cell created.  Requires support from external"
                     " code if timestep changes.  Only really useful for backward Euler cells.")
    group.add_option('-m', '--use-modifiers',
                     action='store_true', default=False,
                     help="[experimental] add modifier functions for certain"
                     " metadata-annotated variables for use in sensitivity analysis (only works if -t Chaste is used)")
    group.add_option('--use-data-clamp',
                     action='store_true', default=False,
                     help="[experimental] generate a data clamp subclass of CVODE cells"
                     " which contains data clamp currents for fitting experimental data (only works if -t CVODE is used)")
    group.add_option('--expose-annotated-variables',
                     action='store_true', default=False,
                     help="expose all oxmeta-annotated variables for access via the GetAnyVariable functionality")
    group.add_option('--expose-all-variables',
                     action='store_true', default=False,
                     help="expose all variables for access via the GetAnyVariable functionality")
    parser.add_option_group(group)
    # Options specific to Functional Curation
    group = optparse.OptionGroup(parser, 'Functional Curation options', "Options specific to use by Functional Curation")
    def protocol_callback(option, opt_str, value, parser):
        """
        Protocols don't always produce normal cardiac cell models.
        However, we want to allow a later option to override these changes.
        """
        parser.values.protocol = value
        parser.values.convert_interfaces = False
        parser.values.use_chaste_stimulus = False
    group.add_option('--protocol',
                     action='callback', callback=protocol_callback, type='string', nargs=1,
                     help="specify a simulation protocol to apply to the model prior to translation")
    group.add_option('--protocol-options', action='store', type='string',
                     help="extra options for the protocol")
    group.add_option('--expose-named-parameters',
                     action='store_true', default=False,
                     help="expose all constant variables with 'name' annotations for access as model parameters")
    parser.add_option_group(group)
    # Settings for lookup tables
    group = optparse.OptionGroup(parser, 'Lookup tables options', "Options specific to the lookup tables optimisation")
    lookup_type_choices = ['entry-below', 'nearest-neighbour', 'linear-interpolation']
    group.add_option('--lookup-type', choices=lookup_type_choices,
                     default='linear-interpolation',
                     help="the type of table lookup to perform [default: %default]."
                     " Choices: " + str(lookup_type_choices))
    group.add_option('--no-separate-lut-class', dest='separate_lut_class',
                     action='store_false', default=True,
                     help="don't put lookup tables in a separate class")
    group.add_option('--row-lookup-method',
                     action='store_true', default=True,
                     help="add and use a method to look up a whole row of a table")
    group.add_option('--no-row-lookup-method', dest='row_lookup_method',
                     action='store_false',
                     help="don't add and use a method to look up a whole row of a table")
    group.add_option('--combine-commutative-tables',
                     action='store_true', default=False,
                     help="optimise a special corner case to reduce the number of tables."
                     " See documentation for details.")
    group.add_option('--lt-index-uses-floor',
                     action='store_true', default=False,
                     help="use floor() to calculate LT indices, instead of just casting")
    group.add_option('--constrain-table-indices',
                     action='store_true', default=False,
                     help="constrain lookup table index variables to remain within the bounds specified,"
                     " rather than throwing an exception if they go outside the bounds")
    group.add_option('--no-check-lt-bounds', dest='check_lt_bounds',
                     action='store_false', default=True,
                     help="[unsafe] don't check for LT indexes going outside the table bounds")
    parser.add_option_group(group)
    # Settings for partial evaluation
    group = optparse.OptionGroup(parser, 'Partial evaluation options', "Options specific to the partial evaluation optimisation")
    group.add_option('--pe-convert-power',
                     action='store_true', default=False,
                     help="convert pow(x,3) to x*x*x; similarly for powers 2 & 4.")
    group.add_option('--no-partial-pe-commutative', dest='partial_pe_commutative',
                     action='store_false', default=True,
                     help="don't combine static operands of dynamic commutative associative applys")
    group.add_option('--no-pe-instantiate-tables', dest='pe_instantiate_tables',
                     action='store_false', default=True,
                     help="don't instantiate definitions that will be tables regardless of usage")
    parser.add_option_group(group)
 
    options, args = parser.parse_args(args, values=default_options)
    if len(args) != 1:
        parser.error("exactly one input CellML file must be specified")
 
    # Some options imply others
    if options.debug_source:
        options.debug = True
    if options.do_jacobian_analysis:
        options.translate_type = 'Maple'
        options.maple_output = False
        options.rush_larsen = False
        options.backward_euler = False
    if options.backward_euler:
        if not options.maple_output:
            parser.error("Backward Euler code generation requires maple output (-j)")
        options.rush_larsen = False
        options.grl1 = False
        options.grl2 = False
    if options.rush_larsen or options.backward_euler or options.grl1 or options.grl2:
        options.translate_type = 'Chaste'
    if options.use_data_clamp and not options.translate_type=='CVODE':
        parser.error("Data clamp option '--use-data-clamp' also requires CVODE ('-t CVODE'). If you are calling this via ConvertCellModel use '--cvode-data-clamp'.")
    # Numba may not be available
    if options.numba:
        try:
            import numba
        except:
            options.numba = False
 
    return options, args[0]
 
 

Referenced by CellMLToNektar.translators.ConfigurationStore.read_configuration_file(), and CellMLToNektar.translators.run().

load_model()

def CellMLToNektar.translators.load_model	(		model_file,
			options
	)

Load and validate a CellML model.

Definition at line 2754 of file translators.py.

def load_model(model_file, options):
    """Load and validate a CellML model."""
    # Setup logging
    logging.thread = None # Hack: we're not multi-threaded, so be slightly quicker...
    if options.debug:
        formatter = logging.Formatter(fmt="%(name)s: %(message)s")
        handler = logging.StreamHandler(sys.stderr)
        handler.setFormatter(formatter)
        handler.addFilter(OnlyDebugFilter())
        if options.debug_source:
            handler.addFilter(OnlyTheseSourcesFilter(options.debug_source))
        logging.getLogger().addHandler(handler)
        logging.getLogger().setLevel(logging.DEBUG)
 
    # We can't translate if some warnings occur, as well as if the model is invalid
    notifier = NotifyHandler(level=logging.WARNING_TRANSLATE_ERROR)
    logging.getLogger('validator').addHandler(notifier)
    v = validator.CellMLValidator(create_relaxng_validator=not options.assume_valid)
    valid, doc = v.validate(model_file, return_doc=True, show_warnings=not options.quiet,
                            check_for_units_conversions=options.warn_on_unit_conversions,
                            warn_on_units_errors=options.warn_on_units_errors,
                            assume_valid=options.assume_valid)
    v.quit()
    del v
 
    if not valid or notifier.messages:
        print >>sys.stderr, model_file,
        if not valid:
            print >>sys.stderr, "is not a valid CellML file"
        else:
            print >>sys.stderr, "contains untranslatable constructs (see warnings above for details)"
        sys.exit(1)
    
    return doc
 

Referenced by CellMLToNektar.translators.run().

run()

def CellMLToNektar.translators.run

(

)

Translate the file given on the command line.

Definition at line 2789 of file translators.py.

def run():
    """Translate the file given on the command line."""
    options, model_file = get_options(sys.argv[1:])
    doc = load_model(model_file, options)
    DEBUG('translate', "+++ Loaded model")
 
    config = ConfigurationStore(doc, options=options)
    for config_file in options.config_file:
        config.read_configuration_file(config_file)
    DEBUG('translate', "+++ Read config")
    
    # Apply protocol, if given
    if options.protocol:
        import protocol
        protocol.apply_protocol_file(doc, options.protocol)
        if options.debug:
            post_proto_cellml = options.outfilename or model_file
            post_proto_cellml = os.path.splitext(post_proto_cellml)[0] + '-proto.cellml.ppp'
            stream = open_output_stream(post_proto_cellml)
            doc.xml(indent=u'yes', stream=stream)
            close_output_stream(stream)
        DEBUG('translate', "+++ Applied protocol")
 
    config.finalize_config()
    DEBUG('translate', "+++ Processed config")
 
    solver_info = SolverInfo(doc.model)
 
    # Generate an interface component, if desired
    translator_klass = CellMLTranslator.translators[options.translate_type]
    if not options.protocol:
        translator_klass.generate_interface(doc, solver_info)
    config.validate_metadata(options.assume_valid)
    DEBUG('translate', "+++ Generated interface")
    
    if options.lut:
        config.find_lookup_variables()
        DEBUG('translate', "+++ Found LT keys")
 
    # These bits could do with improving, as they annotate more than is really needed!
    if options.pe:
        # We need to ensure PE doesn't remove ionic currents needed for GetIIonic
        config.annotate_currents_for_pe()
        # "Need" to ensure pe doesn't remove metadata-annotated variables (when using modifiers or default stimulus?)
        config.annotate_metadata_for_pe()
        DEBUG('translate', "+++ Annotated variables")
    # Deal with the 'expose' options
    config.expose_variables()
 
    class_name = options.class_name
    if not class_name:
        class_name = doc.model.name.replace('-', '_')
        if options.augment_class_name:
            class_name = u'CML_' + class_name
            if options.pe:
                class_name += '_pe'
            if options.lut:
                class_name += '_lut'
            if options.backward_euler:
                class_name += '_be'
            if options.use_modifiers:
                class_name += '_sens'
    if options.protocol:
        # Try to avoid OdeSystemInformation conflicts
        class_name += "_Proto_" + os.path.splitext(os.path.basename(options.protocol))[0]
 
    output_filename = getattr(options, 'outfilename', None)
    if not options.translate and not output_filename:
        output_filename = 'stdout'
 
    if options.units_conversions:
        doc.model.add_units_conversions()
        DEBUG('translate', "+++ Added units conversions")
 
    if options.do_jacobian_analysis:
        lin = optimize.LinearityAnalyser()
        lin.analyse_for_jacobian(doc, V=config.V_variable)
        DEBUG('translate', "+++ Analysed model for Jacobian")
 
    if options.maple_output:
        # Parse Jacobian matrix
        from maple_parser import MapleParser
        mp = MapleParser()
        jacobian_file = file(options.maple_output) # TODO: Error checking
        doc.model._cml_jacobian = mp.parse(jacobian_file)
        doc.model._cml_jacobian_full = mp.JacobianWasFullSize
        jacobian_file.close()
        if not options.backward_euler and doc.model._cml_jacobian_full:
            # Add full jacobian to XML
            solver_info.add_jacobian_matrix()
            solver_info.add_variable_links()
 
    if options.backward_euler:
        # Rearrange linear ODEs
        lin = optimize.LinearityAnalyser()
        lin.analyse_for_jacobian(doc, V=config.V_variable)
        lin.rearrange_linear_odes(doc)
        # Remove jacobian entries that don't correspond to nonlinear state variables
        jacobian = doc.model._cml_jacobian
        if isinstance(jacobian, tuple):
            assert doc.model._cml_jacobian_full
            jacobian = jacobian[1]
        nonlinear_vars = set([v.get_source_variable(recurse=True) for v in doc.model._cml_nonlinear_system_variables])
        def gv(vname):
            return cellml_variable.get_variable_object(doc.model, vname).get_source_variable(recurse=True)
        for var_i, var_j in jacobian.keys():
            if gv(var_i) not in nonlinear_vars or gv(var_j) not in nonlinear_vars:
                del jacobian[(var_i, var_j)]
        if doc.model._cml_jacobian_full:
            # Transform the Jacobian into the form needed by the Backward Euler code
            import maple_parser
            for key, expr in jacobian.iteritems():
                new_expr = None
                if key[0] == key[1]:
                    # 1 on the diagonal
                    new_expr = maple_parser.MNumber(['1'])
                if not (isinstance(expr, maple_parser.MNumber) and str(expr) == '0'):
                    # subtract delta_t * expr
                    args = []
                    if new_expr:
                        args.append(new_expr)
                    args.append(maple_parser.MOperator([maple_parser.MVariable(['delta_t']), expr], 'prod', 'times'))
                    new_expr = maple_parser.MOperator(args, '', 'minus')
                if new_expr:
                    jacobian[key] = new_expr
        # Add info as XML
        solver_info.add_all_info()
        # Analyse the XML, adding cellml_variable references, etc.
        solver_info.add_variable_links()
        solver_info.add_linear_ode_update_equations()
        DEBUG('translate', "+++ Parsed and incorporated Maple output")
    else:
        options.include_dt_in_tables = False
 
    if options.lut:
        # Create the analyser so PE knows which variables are table keys
        lut = optimize.LookupTableAnalyser()
    else:
        lut = None
 
    if options.pe:
        # Do partial evaluation
        pe = optimize.PartialEvaluator()
        pe.parteval(doc, solver_info, lut)
        DEBUG('translate', "+++ Done PE")
 
    if options.lut:
        # Do the lookup table analysis
        lut.analyse_model(doc, solver_info)
        DEBUG('translate', "+++ Done LT analysis")
    
    if options.rush_larsen:
        rl = optimize.RushLarsenAnalyser()
        rl.analyse_model(doc)
        DEBUG('translate', "+++ Done Rush-Larsen analysis")
 
    if options.translate:
        # Translate to code
        initargs = {'add_timestamp': not options.no_timestamp,
                    'options': options}
        transargs = {'v_variable': config.V_variable}
        transargs['row_lookup_method'] = options.row_lookup_method
        transargs['lt_index_uses_floor'] = options.lt_index_uses_floor
        transargs['constrain_table_indices'] = options.constrain_table_indices
        """if issubclass(translator_klass, CellMLToMapleTranslator):
            initargs['omit_constants'] = options.omit_constants
            initargs['compute_full_jacobian'] = options.compute_full_jacobian
        el"""
        from CellMLToNektarTranslator import CellMLToNektarTranslator
        if issubclass(translator_klass, CellMLToNektarTranslator):
            solver_info.add_membrane_ionic_current()
            transargs['use_chaste_stimulus'] = options.use_chaste_stimulus
            transargs['separate_lut_class'] = options.separate_lut_class
            transargs['convert_interfaces'] = options.convert_interfaces
            transargs['use_modifiers'] = options.use_modifiers
            transargs['use_data_clamp'] = options.use_data_clamp
            transargs['dynamically_loadable'] = options.dynamically_loadable
            transargs['use_protocol'] = bool(options.protocol)
        t = translator_klass(**initargs)
        t.translate(doc, model_file, output_filename, class_name=class_name, **transargs)
        cellml_metadata.remove_model(doc.model)
    else:
        # Add a comment element
        comment = pycml.comment_base(
            body=u'\n' + version_comment(not options.no_timestamp) + u'\n')
        doc.xml_insert_before(doc.model, comment)
        # Output annotated model
        stream = open_output_stream(output_filename)
        doc.xml(indent=u'yes', stream=stream)
        close_output_stream(stream)
 
        
    DEBUG('translate', "+++ Done translation")

References CellMLToNektar.utilities.close_output_stream(), CellMLToNektar.utilities.DEBUG(), CellMLToNektar.translators.get_options(), CellMLToNektar.translators.load_model(), CellMLToNektar.utilities.open_output_stream(), and CellMLToNektar.translators.version_comment().

Referenced by Nektar::SolverUtils::FilterFieldConvert.FilterFieldConvert(), and main().

version_comment()

def CellMLToNektar.translators.version_comment

(

note_time = True

)

Generate a version comment, with optional time info.

Definition at line 62 of file translators.py.

def version_comment(note_time=True):
    """Generate a version comment, with optional time info."""
    if note_time:
        t = '\non ' + time.asctime()
    else:
        t = ''
    text = """Processed by pycml - CellML Tools in Python
    (translators: %s, pycml: %s, optimize: %s)%s""" % (
        __version__, pycml.__version__, optimize.__version__, t)
    return text
 
#some debugging function?

Referenced by CellMLToNektar.CellMLToNektarTranslator.CellMLToNektarTranslator.output_includes(), CellMLToNektar.translators.CellMLTranslator.output_top_boilerplate(), and CellMLToNektar.translators.run().

Variable Documentation

__version__

list CellMLToNektar.translators.__version__ = "$Revision: 25950 $"[11:-2]

private

Definition at line 58 of file translators.py.