.. _parameters:

parameters - encapsulates model parameters
==========================================

.. automodule:: pario.parameters
    :synopsis: encapsulates model parameters

**Content**

.. autosummary ::
    pario.parameters.Parameters
    pario.parameters.read
    pario.parameters.fromstring
    pario.parameters.getpar
    pario.parameters.setpar
    pario.parameters.NotPermittedError

.. autoclass:: pario.parameters.Parameters
    :members: _get_mode, _set_mode, _get_names, _copy, _set, _get, _get_quantity, _update, _update_fromstring, _update_fromfile, _tostring, _write, _edit
.. autofunction:: pario.parameters.read
.. autofunction:: pario.parameters.fromstring
.. autofunction:: pario.parameters.getpar
.. autofunction:: pario.parameters.setpar
.. autoclass:: pario.parameters.NotPermittedError



EntityConverter object
----------------------
Since Parameters objects knows so much about themselves, it is
possible to convert between different versions of your input file or
make rules for generating input to another program based on some input
files and the output from your program.  This functionality is supported
through the :class:`pario.parameters.EntityConverter` class.

See the class documentation below for an example.

If the only changes between two versions of an input file is one of:

  * reordering of the parameters
  * change of units
  * adding a new parameter with a default value

you can use the :func:`pario.parameters.simple_converter` to generate
a converter.  Other you have to subclass
:class:`pario.parameters.EntityConverter` .

**Content**

.. autosummary ::
    pario.parameters.EntityConverter
    pario.parameters.ConversionError
    pario.parameters.simple_converter

.. autoclass:: pario.parameters.EntityConverter
    :members:
.. autoclass:: pario.parameters.ConversionError
    :members:
.. autofunction:: pario.parameters.simple_converter



EntityRegistry object
---------------------
In order for the parameter entity conversions to work, the converter
needs to know a definition of the parameter entities.  This is simply done
by creating an entity register

.. doctest::

    >>> ereg = EntityRegistry()

and registering a default input file as a Parameters objects

::

    >>> ereg.register_file('my_default_inputfile.txt')

The `ereg` object is then be passed to the EntityConverter
constructor.

.. autoclass:: pario.parameters.EntityRegistry
    :members:



ParametersFormat subclasses
---------------------------
New file formats can be added by subclassing ParametersFormat.
Predefined includes:

  * 'text' defined by :class:`pario.parameters.TextFormat`
  * 'settings' defined by :class:`pario.parameters.SettingsFormat`

**Content**

.. autosummary ::
    pario.parameters.ParametersFormat
    pario.parameters.TextFormat
    pario.parameters.SettingsFormat
    pario.parameters.InputError

.. autoclass:: pario.parameters.ParametersFormat
    :members:
.. autoclass:: pario.parameters.TextFormat
    :members:
.. autoclass:: pario.parameters.SettingsFormat
    :members:
.. autoclass:: pario.parameters.InputError



Other utilities functions
-------------------------

.. autofunction:: pario.parameters.entity_to_tuple
.. autofunction:: pario.parameters.entity_to_string
.. autofunction:: pario.parameters.get_subclasses
.. autofunction:: pario.parameters.typeconvert