.. _db-py_simo:

####################
db.py
####################
   
::

    >>> from simo.db.simodb.test.test_classes import *
    >>> from simo.builder import names
    >>> from minimock import Mock
    >>> tdf = open('../../simulator/xml/schemas/Typedefs_SIMO.xsd')
    >>> typedef = tdf.read()
    >>> tdf.close()
    >>> sf = open('../../simulator/xml/schemas/operation2modelchains.xsd')
    >>> schema = sf.read()
    >>> sf.close()
    >>> xml = u'''<SIMO_operation_mapping xmlns="http://www.simo-project.org/simo" 
    ... xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    ... xsi:schemaLocation="http://www.simo-project.org/simo 
    ...                     ./schemas/operation_mapping.xsd">
    ... <operation>
    ...     <from>
    ...         <name>thinning</name>
    ...     </from>
    ...     <to>
    ...         <model_chain>Calculate thinning limits</model_chain>
    ...         <model_chain>Forced low thinning</model_chain>
    ...     </to>
    ... </operation>
    ... <operation>
    ...     <from>
    ...         <name>first_thinning</name>
    ...     </from>
    ...     <to>
    ...         <model_chain>Calculate thinning limits</model_chain>
    ...         <model_chain>Forced first thinning</model_chain>
    ...     </to>
    ... </operation>
    ... <operation>
    ...     <from>
    ...         <name>clearcut</name>
    ...     </from>
    ...     <to>            
    ...         <model_chain>Forced clearcut</model_chain>
    ...     </to>
    ... </operation>
    ... <operation>
    ...     <from>
    ...         <name>strip_cutting</name>
    ...     </from>
    ...     <to>            
    ...         <model_chain>Forced stripcut</model_chain>
    ...         <model_chain>Calculate productive value</model_chain>
    ...     </to>
    ... </operation>
    ... </SIMO_operation_mapping>'''
    >>> sf = open('../../simulator/xml/schemas/aggregation_modelbase.xsd')
    >>> mbschema = sf.read()
    >>> sf.close()
    >>> mbxml = u'''<aggregation_base xmlns="http://www.simo-project.org/simo"
    ...               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...               <model>
    ...                  <name>sum</name>
    ...                  <description>desc...</description>
    ...                  <implemented_at>simoaggr.py</implemented_at>
    ...                  <vector_implementation>true</vector_implementation>
    ...               </model>
    ...           </aggregation_base>'''
    >>> mcsf = open('../../simulator/xml/schemas/model_chain.xsd')
    >>> mcschema = mcsf.read()
    >>> mcsf.close()
    >>> mcxml = u'''<model_chains 
    ...    xsi:schemaLocation="http://www.simo-project.org/simo 
    ...    ../../schemas/model_chain.xsd"
    ...    xmlns="http://www.simo-project.org/simo" 
    ...    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...    <chain_group name="Forced thinnings">
    ...      <model_chain evaluate_at="comp_unit" name="Calculate thinning limits">
    ...           <task name="Calculate thinning limits">
    ...              <model>
    ...                 <name>Thinning_limits_JKK</name>
    ...                 <prediction>
    ...                     <parameters>
    ...                         <parameter>
    ...                             <name>THINNING_LEVEL</name>
    ...                             <value>0.5</value>
    ...                         </parameter>
    ...                     </parameters>
    ...                 </prediction>
    ...             </model>
    ...         </task>
    ...     </model_chain>
    ... </chain_group>
    ... </model_chains>'''
    >>> from simo.builder.modelbase.predictionmodel import PredictionModel
    >>> from lxml import etree
    >>> xml2 = u'''<model_group name="Distribution models">
    ...             <model>
    ...             <name>Volume_BAHdomF</name>
    ...             <implemented_at>StandModels.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>
    ...                 </variable>
    ...             </variables>
    ...             <parameters>
    ...                 <parameter>
    ...                     <name>THINNING_LEVEL</name>
    ...                 </parameter>
    ...             </parameters>
    ...             <result>
    ...                 <object>self</object>
    ...                 <variables>
    ...                     <variable>
    ...                         <name>PVland_Sp</name>
    ...                     </variable>
    ...                 </variables>
    ...             </result>
    ...         </model>
    ...     </model_group>'''
    >>> class Validator:
    ...     def elem_name(self, text):
    ...         return text
    ...     def variable_ind(self, level, variable, active=False):
    ...         return (1,1)
    ...     def add_model(self, mname, mtype):
    ...         pass
    ...     def add_error(self, text):
    ...         print 'error:', text
    ...     errors = []
    ...     warnings = []
    >>> elem = etree.fromstring(xml2)
    >>> pr = PredictionModel('', elem[0], Validator(), 
    ...                      '../../simulator/models/prediction', 
    ...                      elem.attrib['name'])
    >>> pr.param_names
    ['THINNING_LEVEL']
    >>> pr.param_limits
    [None]
    >>> pr.n_params
    1
    >>> mimpl = {names.PREDICTION: {'Thinning_limits_JKK': pr}}

*********************
class SimoDB(object):
*********************

def __init__(self, file, create_new=False, read_only=False):
============================================================

Initializes the database, creating or opening the necessary files ::

   >>> from simo.db.simodb.db import SimoDB
   >>> db = SimoDB('db/simodb/test/test.fs', True)
   >>> db.dbroot['test'] = 'test'
   >>> db.commit()
   >>> print db.dbroot['test']
   test
   >>> db.close()
   >>> db = SimoDB('db/simodb/test/test.fs', False)
   >>> print db.dbroot['test']
   test
   >>> db2 = SimoDB('db/simodb/test/test.fs', False, read_only=True)
   >>> db.close()
   >>> db2.close()
   >>> db2 = None
   >>> db = SimoDB('db/simodb/test/test2.fs', True)
   
def set_schema(self, type, schema):
===================================

Sets a new type to the db if not present and sets a schema for that type.
Returns True if successful, False if not.::

   >>> try:
   ...     db.set_schema('operation2modelchains', schema)
   ... except ValueError, e:
   ...     print e
   Typedef not set
   >>> db.typedef = typedef 
   >>> db.set_schema('operation2modelchains', schema)
   >>> db.set_schema('modelbase', mbschema, 'aggregation')
   >>> db.set_schema('modelchain', mcschema)
   >>> try:
   ...     db.set_schema('test', mcschema)
   ... except ValueError, e:
   ...     print e
   unsupported SIMO class type 'test'

def get_schema(self, simoclass, atype):
=======================================

Returns the schema of the given type or None if the type is not available.::

    >>> db.get_schema('operation2modelchains')==schema
    True
    >>> db.get_schema('modelbase', 'aggregation')==mbschema
    True
    >>> db.get_schema('modelchain')==mcschema
    True
    >>> db.get_schema('Something else')
   
def set_xml(self, simoclass, xml, mtype):
=========================================   
   
Stores the xml to the database. This triggers object instance creation as well.
The xml parameter is in general a tuple of (name, xml text, lexicon object instance). In case of model chain XML the tuple consists of (name, xml text, lexicon object instance, chain type, model impelementation). For modelbase XML the tuple consists of: (name, xml text, lexicon object instance, directory path, model type). The directory path refers to where the implementations of models are located.

The method returns a tuple of (top level error, ok, warnings, errors). Raises an ValueError if the schema has not been set. ::
      
   >>> db.set_xml('operation2modelchains', ('testxml', xml, XMLLexicon()))
   (None, True, [], set([]))
   >>> db.set_xml('modelbase', ('testxml', mbxml, ModelLexicon(), '',
   ...                          'aggregation'))
   (None, True, [], set([]))
   >>> db.set_xml('modelchain', ('testxml', mcxml, ChainLexicon(), 'simulation', 
   ...                           mimpl))
   (None, True, [], set([]))
   >>> db.set_xml('modelchain', ('testxml2', mcxml, ChainLexicon(), 'simulation', 
   ...                           mimpl))
   (None, True, [], set([]))
   
def get_xml(self, simoclass, name):
===================================

Returns the xmltext set to the given name in the given type in the database.
Returns (None, None) if either the type or the name is not available ::

   >>> data = db.get_xml('operation2modelchains', 'testxml')
   >>> data[0][:23]
   u'<SIMO_operation_mapping'
   >>> data[1]
   True
   >>> data = db.get_xml('modelbase', 'testxml', 'aggregation')
   >>> data[0][:17]
   u'<aggregation_base'
   >>> data[1]
   True
   >>> data = db.get_xml('modelchain', 'testxml', 'simulation')
   >>> data[0][:13]
   u'<model_chains'
   >>> data[1]
   True
   >>> db.get_xml('something else', 'testxml')
   (None, None)

def get_names(self, simoclass, atype):
======================================

Returns a list of the names of the xmls that have been saved to the database. Modelchain and modelbase need chain/model type definition as well::

    >>> db.get_names('operation2modelchains')
    ['testxml']
    >>> db.get_names('modelbase', 'aggregation')
    ['testxml']
    >>> db.get_names('modelchain', 'simulation')
    ['testxml', 'testxml2']
    >>> db.get_names('something else') 

def get_obj(self, simoclass, name):
===================================

Returns an instance of the given type and name::

    >>> ob = db.get_obj('operation2modelchains', 'testxml')
    >>> ob.operation_mapping['first_thinning'] # doctest: +NORMALIZE_WHITESPACE
    ['Calculate thinning limits', 'Forced first thinning'] 
    >>> ob.forced_op_chains # doctest: +NORMALIZE_WHITESPACE
    set(['Calculate thinning limits', 'Forced stripcut', 'Forced low thinning', 
         'Forced clearcut', 'Calculate productive value', 'Forced first thinning'])
    >>> ob = db.get_obj('modelbase', 'testxml', 'aggregation')
    >>> print ob.keys()
    ['sum']
    >>> mbo = ob['sum']
    >>> mbo.type
    'aggregation'
    >>> mbo.name
    'sum'
    >>> mbo._lib
    'simoaggr.py'
    >>> mbo.language
    'python'
    >>> mbo.dirs
    ''
    >>> mc = db.get_obj('modelchain', 'testxml', 'simulation')# doctest: +ELLIPSIS
    >>> mc.chain_groups['Forced thinnings']
    ['Calculate thinning limits']
    >>> mc.chain_type
    'simulation'
    >>> len(mc.chains)
    1
    >>> c = mc.chains[0]
    >>> c.condition
    >>> c.evaluate_at
    'comp_unit'
    >>> c.name
    'Calculate thinning limits'
    >>> len(c.tasks)
    1
    >>> t = c.tasks[0]
    >>> t.name
    'Calculate thinning limits'
    >>> t.value_fixer
    False
    >>> t.model # doctest: +ELLIPSIS
    <simo.builder.modelbase.predictionmodel.PredictionModel object at ...>
    >>> t.model._v_func #doctest: +ELLIPSIS
    <function Volume_BAHdomF at ...>
    >>> t.condition_parser
    >>> t.validator
    >>> p = t.model_param
    >>> p.parameters
    [0.5]
    >>> p.rect_factor
    1.0
    >>> p.risk_level
    1
    >>> p._validator
    
def get_valid(self, simoclass=None):
====================================
Returns if the given simoclass is valid or if simoclass is None, information on all the simoclasses.

    >>> db.get_valid('modelchain') == \
    ... {'valid': True, 'types': {'simulation': {'testxml': True, 
    ...                                          'testxml2': True}}}
    True
    >>> db.get_valid() == \
    ... {'modelchain': {'valid': True, 
    ...                 'types': {'simulation': {'testxml': True, 
    ...                                          'testxml2': True}}}, 
    ...  'problem_definition': {'valid': False, 'names': {}}, 
    ...  'lexicon': {'valid': False, 'names': {}}, 
    ...  'text2data': {'valid': False, 'names': {}}, 
    ...  'operation2modelchains': {'valid': True, 'names': {'testxml': True}}, 
    ...  'aggregation_definition': {'valid': False, 'names': {}}, 
    ...  'expression_definition': {'valid': False, 'names': {}},
    ...  'message_translation': {'valid': False, 'names': {}}, 
    ...  'lexicon_translation': {'valid': False, 'names': {}}, 
    ...  'modelbase': {'valid': True, 'types': {'aggregation': {'testxml': True}}},
    ...  'text2operation': {'valid': False, 'names': {}}, 
    ...  'output_constraint': {'valid': False, 'names': {}}, 
    ...  'simulation_control': {'valid': False, 'names': {}}}
    True