CellMLToNektar.pycml.UnitsSet Class Reference

Inheritance diagram for CellMLToNektar.pycml.UnitsSet:

Public Member Functions
def	__new__ (cls, iterable=[], expression=None)
def	__init__ (self, iterable=[], expression=None)
def	copy (self)
def	get_consistent_set (self, desired_units)
def	equals (self, other)
def	extract (self, check_equality=False)
def	set_expression (self, expr)
def	get_expression (self)
def	simplify (self, other_units=None, other_exponent=1)
def	dimensionally_equivalent (self, other_units)
def	description (self)

Private Member Functions
def	_add_source (self, units, src_units_set, src_units)
def	_get_sources (self, units)

Private Attributes
	_expression
	_sources

Detailed Description

A set of cellml_units objects.

This class behaves like a normal set, but also has additional
methods for operations specific to sets of <units> objects:
  simplify - allow for multiplication of sets of units
  dimensionally_equivalent - compare 2 sets of units for dimensional equivalence
  description - describe the units in this set

All units in the set (normally) must be dimensionally equivalent.  The exception is when dealing with
Functional Curation protocols which can defined units conversion rules for non-scaling cases.  We can
then have sets of alternative units in different dimensions, and the get_consistent_set method helps
with selecting from these.

Definition at line 2349 of file pycml.py.

Constructor & Destructor Documentation

__init__()

def CellMLToNektar.pycml.UnitsSet.__init__	(		self,
			iterable = [],
			expression = None
	)

Definition at line 2372 of file pycml.py.

    def __init__(self, iterable=[], expression=None):
        super(UnitsSet, self).__init__(iterable)
        self._expression = expression
        self._sources = {}
        return

Member Function Documentation

__new__()

def CellMLToNektar.pycml.UnitsSet.__new__	(		cls,
			iterable = [],
			expression = None
	)

Work around annoyance in set implementation of python 2.4.2c1 and on.
setobject.c checks for keyword arguments in its __new__ instead of its
__init__, so we get an error
'TypeError: set() does not take keyword arguments' if we don't do this.

Definition at line 2363 of file pycml.py.

    def __new__(cls, iterable=[], expression=None):
        """
        Work around annoyance in set implementation of python 2.4.2c1 and on.
        setobject.c checks for keyword arguments in its __new__ instead of its
        __init__, so we get an error
        'TypeError: set() does not take keyword arguments' if we don't do this.
        """
        return super(UnitsSet, cls).__new__(cls, iterable)
    

_add_source()

def CellMLToNektar.pycml.UnitsSet._add_source (   self,   units,   src_units_set,   src_units  )

private

Add source units for the given units.

This stores references to how units were arrived at when doing a
simplify.  It manages lists of (src_units_set, src_units) pairs for
each units definition in this set.

If src_units_set has no associated expression, then it is
considered to be a temporary object, created for example whilst
doing an n-ary times operation.  In this case, we add its list of
sources for src_units to our sources list instead.

Definition at line 2446 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet._sources, Nektar::LibUtilities::CmdLineArg.description, and CellMLToNektar.pycml.UnitsSet.description().

    def _add_source(self, units, src_units_set, src_units):
        """Add source units for the given units.

        This stores references to how units were arrived at when doing a
        simplify.  It manages lists of (src_units_set, src_units) pairs for
        each units definition in this set.

        If src_units_set has no associated expression, then it is
        considered to be a temporary object, created for example whilst
        doing an n-ary times operation.  In this case, we add its list of
        sources for src_units to our sources list instead.
        """
        if not units in self._sources:
            self._sources[units] = []
        if not hasattr(src_units_set, '_expression'):
            print self.description(), units.description()
            print src_units_set.description(), src_units.description()
        if src_units_set._expression:
            self._sources[units].append((src_units_set, src_units))
        else:
            try:
                self._sources[units].extend(src_units_set._sources[src_units])
            except KeyError:
                # No sources list found.  This can happen if we do
                # dimensionless.simplify(...), for example, to evaluate powers.
                pass
        return
    

_get_sources()

def CellMLToNektar.pycml.UnitsSet._get_sources (   self,   units  )

private

Return the sources list for the given units.

Definition at line 2474 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet._sources.

    def _get_sources(self, units):
        """Return the sources list for the given units."""
        return self._sources.get(units, [])

copy()

def CellMLToNektar.pycml.UnitsSet.copy

(

self

)

Do a shallow copy of this UnitsSet.

Definition at line 2378 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet._expression, and CellMLToNektar.pycml.UnitsSet._sources.

    def copy(self):
        """Do a shallow copy of this UnitsSet."""
        new_set = super(UnitsSet, self).copy()
        new_set._expression = self._expression
        new_set._sources = {}
        for units, src_list in self._sources.iteritems():
            new_set._sources[units] = copy.copy(src_list)
        return new_set
    

description()

def CellMLToNektar.pycml.UnitsSet.description

(

self

)

Describe these units.

Shows the descriptions of each member, as though this were a set of
unicode strings.  If multiple members have the same description,
only one instance is shown.  If only one description is being shown,
then the curly brackets are not added.

Definition at line 2525 of file pycml.py.

Referenced by CellMLToNektar.pycml.UnitsSet._add_source(), and CellMLToNektar.pycml.cellml_units.uniquify_tuple().

    def description(self):
        """Describe these units.

        Shows the descriptions of each member, as though this were a set of
        unicode strings.  If multiple members have the same description,
        only one instance is shown.  If only one description is being shown,
        then the curly brackets are not added.
        """
        desc = list(set(u.description() for u in self))
        desc.sort()
        if len(desc) > 1:
            desc = u'{' + u','.join(desc) + u'}'
        else:
            desc = desc[0]
        return desc

dimensionally_equivalent()

def CellMLToNektar.pycml.UnitsSet.dimensionally_equivalent	(		self,
			other_units
	)

Check for dimensional equivalence between sets of units.

Since all units in each set should be equivalent, we just compare
an arbitrary member from each set.

other_units may be a single cellml_units instance, in which case we
compare an arbitrary member of self to it.

Definition at line 2512 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet.extract().

    def dimensionally_equivalent(self, other_units):
        """Check for dimensional equivalence between sets of units.

        Since all units in each set should be equivalent, we just compare
        an arbitrary member from each set.

        other_units may be a single cellml_units instance, in which case we
        compare an arbitrary member of self to it.
        """
        u1 = self.extract()
        u2 = other_units.extract()
        return u1.dimensionally_equivalent(u2)

equals()

def CellMLToNektar.pycml.UnitsSet.equals	(		self,
			other
	)

Test whether the units in the set are equal to those in another set.

Definition at line 2413 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet.extract().

    def equals(self, other):
        """Test whether the units in the set are equal to those in another set."""
        try:
            equal = self.extract(check_equality=True).equals(other.extract(check_equality=True))
        except ValueError:
            equal = False
        return equal

extract()

def CellMLToNektar.pycml.UnitsSet.extract	(		self,
			check_equality = False
	)

Extract a representative element from this set.

This is intended to be used to get the cellml_units object from a singleton set.

If check_equality is True, check that all members of this set have the same multiplicative factor.

Definition at line 2421 of file pycml.py.

References CellMLToNektar.pycml.get_multiplicative_factor(), and CellMLToNektar.pycml.get_offset().

Referenced by CellMLToNektar.pycml.UnitsSet.dimensionally_equivalent(), CellMLToNektar.pycml.UnitsSet.equals(), and CellMLToNektar.pycml.UnitsSet.get_consistent_set().

    def extract(self, check_equality=False):
        """Extract a representative element from this set.

        This is intended to be used to get the cellml_units object from a singleton set.
        
        If check_equality is True, check that all members of this set have the same multiplicative factor.
        """
        representative = iter(self).next()
        if check_equality:
            for u in self:
                if not u._rel_error_ok(u.expand().get_multiplicative_factor(),
                                       representative.expand().get_multiplicative_factor(),
                                       1e-6):
                    raise ValueError("UnitsSet equality check failed")
                if u.is_simple() and not u._rel_error_ok(u.expand().get_offset(),
                                                         representative.expand().get_offset(),
                                                         1e-6):
                    raise ValueError("UnitsSet equality check failed")
        return representative
    

get_consistent_set()

def CellMLToNektar.pycml.UnitsSet.get_consistent_set	(		self,
			desired_units
	)

Extract a subset of the units in this set that are dimensionally equivalent.

When dealing with potential non-scaling conversions, an expression may have potential units that are
not within the same dimension.  However, when deciding on the units for the expression most operations
need to handle a set of options that *are* within the same dimension, and this operation supports that.

Given a cellml_units object for the desired units of the expression, this method first tries to create
a UnitsSet containing just our members in the same dimension.  If we have no members in the desired
dimension, then we check that all members of this set are in the same dimension, and return the set
itself - there should never be more than 2 different dimensions to choose from (I hope!).

Definition at line 2387 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet._expression, CellMLToNektar.pycml.UnitsSet._sources, and CellMLToNektar.pycml.UnitsSet.extract().

    def get_consistent_set(self, desired_units):
        """Extract a subset of the units in this set that are dimensionally equivalent.
        
        When dealing with potential non-scaling conversions, an expression may have potential units that are
        not within the same dimension.  However, when deciding on the units for the expression most operations
        need to handle a set of options that *are* within the same dimension, and this operation supports that.

        Given a cellml_units object for the desired units of the expression, this method first tries to create
        a UnitsSet containing just our members in the same dimension.  If we have no members in the desired
        dimension, then we check that all members of this set are in the same dimension, and return the set
        itself - there should never be more than 2 different dimensions to choose from (I hope!).
        """
        new_set = UnitsSet([], expression=self._expression)
        for units in self:
            if units.dimensionally_equivalent(desired_units):
                new_set.add(units)
                new_set._sources[units] = copy.copy(self._sources[units])
        if not new_set:
            rep_u = self.extract()
            for units in self:
                if not units.dimensionally_equivalent(rep_u):
                    raise ValueError("Unexpected dimensional variation in UnitsSet; " + rep_u.description() + " and " + units.description()
                                     + " do not match.")
            new_set = self
        return new_set

get_expression()

def CellMLToNektar.pycml.UnitsSet.get_expression

(

self

)

Return an expression that has these units.

Definition at line 2478 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet._expression.

    def get_expression(self):
        """Return an expression that has these units."""
        return self._expression
    

set_expression()

def CellMLToNektar.pycml.UnitsSet.set_expression	(		self,
			expr
	)

Store a reference to the expression that has these units.

Definition at line 2441 of file pycml.py.

References CellMLToNektar.pycml.UnitsSet._expression.

    def set_expression(self, expr):
        """Store a reference to the expression that has these units."""
        self._expression = expr
        return

simplify()

def CellMLToNektar.pycml.UnitsSet.simplify	(		self,
			other_units = None,
			other_exponent = 1
	)

Simplify the units in this set.

Each cellml_units object in this set is simplified, and a new
UnitsSet returned with the results.

If other_units is not None, then products of units are
calculated.  The returned set is essentially the cartesian
product of the input sets under the simplify operator, i.e.
u1.simplify(other_units=u2, other_exponent=other_exponent)
will be called for each member u1 of self and each member u2
of other_units (if other_units is a UnitsSet; otherwise
u2=other_units).

Definition at line 2482 of file pycml.py.

    def simplify(self, other_units=None, other_exponent=1):
        """Simplify the units in this set.

        Each cellml_units object in this set is simplified, and a new
        UnitsSet returned with the results.

        If other_units is not None, then products of units are
        calculated.  The returned set is essentially the cartesian
        product of the input sets under the simplify operator, i.e.
        u1.simplify(other_units=u2, other_exponent=other_exponent)
        will be called for each member u1 of self and each member u2
        of other_units (if other_units is a UnitsSet; otherwise
        u2=other_units).
        """
        result_set = UnitsSet()
        for units in self:
            if other_units is None:
                res_u = units.simplify()
                result_set.add(res_u)
                result_set._add_source(res_u, self, units)
            else:
                if isinstance(other_units, cellml_units):
                    other_units = UnitsSet([other_units])
                for u in other_units:
                    res_u = units.simplify(u, other_exponent)
                    result_set.add(res_u)
                    result_set._add_source(res_u, self, units)
                    result_set._add_source(res_u, other_units, u)
        return result_set

Member Data Documentation

_expression

CellMLToNektar.pycml.UnitsSet._expression

private

Definition at line 2374 of file pycml.py.

Referenced by CellMLToNektar.pycml.UnitsSet.copy(), CellMLToNektar.pycml.UnitsSet.get_consistent_set(), CellMLToNektar.pycml.UnitsSet.get_expression(), and CellMLToNektar.pycml.UnitsSet.set_expression().

_sources

CellMLToNektar.pycml.UnitsSet._sources

private

Definition at line 2375 of file pycml.py.

Referenced by CellMLToNektar.pycml.UnitsSet._add_source(), CellMLToNektar.pycml.UnitsSet._get_sources(), CellMLToNektar.pycml.UnitsSet.copy(), and CellMLToNektar.pycml.UnitsSet.get_consistent_set().