.. _model-py:

########
model.py
########

::

    >>> from simo.builder.modelbase.model import Model
    >>> from simo.builder.modelbase.model import POModel
    >>> from lxml import etree
    >>> xml = u'''<model>
    ...             <name>Productive_value_of_land_pine_Pukkala</name>
    ...             <implemented_at>StaticstandModels.dll</implemented_at>
    ...             <implemented_in>C</implemented_in>
    ...             <author>
    ...                 <name>Timo Pukkala</name>
    ...             </author>
    ...             <description>    ...</description>
    ...             <published_in>    ...</published_in>
    ...             <species_list>
    ...                 <species>1</species>
    ...             </species_list>
    ...             <geographical_coverage>    ...</geographical_coverage>
    ...             <applies_for>    ...</applies_for>
    ...             <research_material>    ...</research_material>
    ...             <variables>
    ...                 <variable>
    ...                     <name>TS</name>
    ...                     <level>comp_unit</level>
    ...                     <limits>
    ...                         <lower_limit>700</lower_limit>
    ...                         <upper_limit>1300</upper_limit>
    ...                     </limits>
    ...                 </variable>
    ...             </variables>
    ...             <parameters>
    ...                 <parameter>
    ...                     <name>IR</name>
    ...                     <limits>
    ...                         <lower_limit>0</lower_limit>
    ...                         <upper_limit>20</upper_limit>
    ...                     </limits>
    ...                 </parameter>
    ...             </parameters>
    ...             <result>
    ...                 <object>self</object>
    ...                 <variables>
    ...                     <variable>
    ...                         <name>PVland_Sp</name>
    ...                     </variable>
    ...                 </variables>
    ...             </result>
    ...         </model>'''
    >>> class Validator:
    ...     def elem_name(self, text):
    ...         return text
    ...     def variable_ind(self, level, variable, active=False):
    ...         return (1,1)
    ...     def add_error(self, errorstr):
    ...         pass
    >>> elem = etree.fromstring(xml)


********************
class Model(object):
********************

Super class for all modelbase model classes.

Properties:

- type: get model type as string
- name: get model name as string
- language: get model implementation language as string
- dirs: get model library directories as a list of strings
- function: get model function object
- library: get model library object
- wrapper: get model library wrapper object


def __init__(self):
===================

::
    >>> m = Model()


def load_function(self, validator):
===================================

Load model function object from model library::

    >>> m._name = 'dummymodel'
    >>> m._lang = 'python'
    >>> m._lib = 'dummylib.py'
    >>> m._dirs = ['builder/modelbase/test']
    >>> m.load_function(Validator())
    True
    >>> m.function # doctest: +ELLIPSIS
    <function dummymodel at ...>


def __load_library(self, validator):
====================================

Load the model library and wrapper module from the given path.


def __load_function_object(self, validator):
============================================

Load model function object from model wrapper.


*********************
class POModel(Model):
*********************

Super class for prediction and operation models.

Properties:

- type: get model type as string
- name: get model name as string
- language: get model implementation language as string
- dirs: get model library directories as a list of strings
- function: get model function object
- library: get model library object
- wrapper: get model library wrapper object


Attributes:

- n_vars: number of input variables
- vars: input variables in a dictionary: level as the key and value is a dictionary with the structure {'index': <variable indices in a list>, 'order': <variable oreder in a list>, 'limits': <variable limits in a list>}
- n_params: number of input parameters
- params: number of input parameters in a list where each item is a (<parameter name>, <parameter limits>) -tuple


def __init__(self, ns, elem, validator, dir):
=============================================

    >>> m = POModel('', elem, Validator(), 'dummydir')
    >>> m.n_vars
    1
    >>> m.vars[1]['index']
    array([1])
    >>> m.vars[1]['order']
    [0]


def __parse_parameters(self, ns, elem):
=======================================

Parse model parameters and possible limits set for the parameter values.


def __parse_variables(self, ns, elem):
======================================

Parse model variable definitions (data level, variable name) and limits set for the variable values.


********************
class Limit(object):
********************

Class for handling model variable limits.


def __init__(self, ns, elem):
=============================

Construct variable/parameter limits from XML element::

    >>> from lxml import etree
    >>> from simo.builder.modelbase.model import Limit
    >>> xml = u'''<limits>
    ...         <lower_limit>700</lower_limit>
    ...         <upper_limit>1300</upper_limit>
    ...     </limits>'''
    >>> ns = ''
    >>> elem = etree.fromstring(xml)
    >>> limits = Limit(ns, elem)
    >>> limits.lower
    700.0
    >>> limits.upper
    1300.0


def check(self, values):
========================

Check if a value (or an array of values) is inside limits::

    >>> import numpy
    >>> values = numpy.array([600,700,1000,1300,1400], dtype=float)
    >>> limits.check(values)
    array([False,  True,  True,  True, False], dtype=bool)


def limitstr(self, variable):
=============================

Return a string representation of the limits::

    >>> limits.limitstr('VARNAME')
    "700.0 <= 'VARNAME' <= 1300.0"