<commit_before>.. _py_mechanisms:

Cable cell mechanisms
=====================

When :ref:`decorating <cablecell-decoration>` a cable cell, we use a :py:class:`mechanism` type to describe a
mechanism that is to be painted or placed on the cable cell.

.. py:class:: mechanism

    Mechanisms describe physical processes, distributed over the membrane of the cell.
    *Density mechanisms* are associated with regions of the cell, whose dynamics are
    a function of the cell state and their own state where they are present.
    *Point mechanisms* are defined at discrete locations on the cell, which receive
    events from the network.
    A third, specific type of density mechanism, which describes ionic reversal potential
    behaviour, can be specified for cells or the whole model.

    The :class:`mechanism` type is a simple wrapper around a mechanism
    :attr:`mechanism.name` and a dictionary of named parameters.

    Mechanisms have two types of parameters:

    * global parameters: a scalar value that is the same for all instances
      of a mechanism.
    * range parameters: the value of range parameters is defined for each instance
      of the mechanism on a cell. For density mechanisms, this means one value for
      each :term:`control volume` on which it is present.

    The method for setting a parameter depends on its type.
    If global parameters change, we are effectively defining a new type
    of mechanism, so global parameter information is encoded in the
    name.
    Range parameters are set using a dictionary of name-value pairs.

    .. code-block:: Python

        import arbor

        # hh dynamics with default parameters.
        hh = arbor.mechanism('hh')

        # A passive leaky channel with custom parameters
        pas = arbor.mechanism('pas/e=-55.0', {'g': 0.02})

        # Reversal potential using Nernst equation with GLOBAL parameter values
        # for Faraday's constant and the target ion species, set with a '/' followed
        # by comma-separated list of parameter after the base mechanism name.
        rev = arbor.mechanism('nernst/F=96485,x=ca')

    .. method:: mechanism(name, params)

        constructor for mechanism with *name* and range parameter overrides *params*,
        for example: ``arbor.mechanism(name='pas', params={'g': 0.01})``.

        :param name: name of mechanism.
        :type name: str
        :param params: A dictionary of parameter values, with parameter name as key.
        :type params: dict[str, double]

    .. method:: mechanism(name)
        :noindex:

        constructor for mechanism.
        The *name* can be either the name of a mechanism in the catalogue,
        e.g.  ``arbor.mechanism('pas')``, or an implicitly derived mechanism,
        e.g. ``arbor.mechanism('nernst/k')``.

    .. method:: set(name, value)

        Set new value for a parameter.

        :param name: name of the parameter.
        :type name: str
        :param value: value of the parameter.
        :type value: float

    .. py:attribute:: name
        :type: str

        The name of the mechanism.

    .. py:attribute:: values
        :type: dict

        A dictionary of key-value pairs for the parameters.

    .. code-block:: Python

        import arbor

        # Create pas mechanism with default parameter values (set in NOMDL file).
        m1 = arbor.mechanism('pas')

        # Create default mechainsm with custom conductance (range).
        m2 = arbor.mechanism('pas', {'g', 0.1})

        # Create a new pas mechanism with that changes reversal potential (global).
        m3 = arbor.mechanism('pas/e=-45')

        # Create an instance of the same mechanism, that also sets conductance (range).
        m4 = arbor.mechanism('pas/e=-45', {'g', 0.1})

        # This is an equivalent to m4, using set method to specify range parameters.
        m5 = arbor.mechanism('pas/e=-45')
        m5.set('g', 0.1)

        # Decorate the 'soma' on a cable_cell.

        cell.paint('"soma"', m1)
        cell.paint('"soma"', m2) # Error: can't place the same mechanism on overlapping regions
        cell.paint('"soma"', m3) # This would be ok: m3 is a new, derived mechanism by virtue of
                                 # having a different name, i.e. 'pas/e=-45' vs. 'pas'.


.. py:class:: mechanism_info

    Meta data about the fields and ion dependencies of a mechanism.
    The data is presented as read-only attributes.

    .. code-block:: Python

        import arbor
        cat = arbor.default_catalogue()

        # Get mechanism_info for the 'expsyn' mechanism.
        mech = cat['expsyn']

        # Query the mechanism_info for information about parameters.<commit_msg>Improve mechanism painting documentation (#1573)<commit_after>.. _py_mechanisms:

Cable cell mechanisms
=====================

When :ref:`decorating <cablecell-decoration>` a cable cell, we use a :py:class:`mechanism` type to describe a
mechanism that is to be painted or placed on the cable cell.

.. py:class:: mechanism

    Mechanisms describe physical processes, distributed over the membrane of the cell.
    *Density mechanisms* are associated with regions of the cell, whose dynamics are
    a function of the cell state and their own state where they are present.
    *Point mechanisms* are defined at discrete locations on the cell, which receive
    events from the network.
    A third, specific type of density mechanism, which describes ionic reversal potential
    behaviour, can be specified for cells or the whole model.

    The :class:`mechanism` type is a simple wrapper around a mechanism
    :attr:`mechanism.name` and a dictionary of named parameters.

    Mechanisms have two types of parameters:

    * global parameters: a scalar value that is the same for all instances
      of a mechanism.
    * range parameters: the value of range parameters is defined for each instance
      of the mechanism on a cell. For density mechanisms, this means one value for
      each :term:`control volume` on which it is present.

    The method for setting a parameter depends on its type.
    If global parameters change, we are effectively defining a new type
    of mechanism, so global parameter information is encoded in the
    name.
    Range parameters are set using a dictionary of name-value pairs.

    .. code-block:: Python

        import arbor

        # hh dynamics with default parameters.
        hh = arbor.mechanism('hh')

        # A passive leaky channel with custom parameters
        pas = arbor.mechanism('pas/e=-55.0', {'g': 0.02})

        # Reversal potential using Nernst equation with GLOBAL parameter values
        # for Faraday's constant and the target ion species, set with a '/' followed
        # by comma-separated list of parameter after the base mechanism name.
        rev = arbor.mechanism('nernst/F=96485,x=ca')

    Mechanisms can be painted to a region. Different mechanisms can be painted on top of each other.

    .. code-block:: Python

        import arbor

        # Create pas mechanism with default parameter values (set in NOMDL file).
        m1 = arbor.mechanism('pas')

        # Create default mechainsm with custom conductance (range).
        m2 = arbor.mechanism('pas', {'g', 0.1})

        # Create a new pas mechanism with that changes reversal potential (global).
        m3 = arbor.mechanism('pas/e=-45')

        # Create an instance of the same mechanism, that also sets conductance (range).
        m4 = arbor.mechanism('pas/e=-45', {'g', 0.1})

        # This is an equivalent to m4, using set method to specify range parameters.
        m5 = arbor.mechanism('pas/e=-45')
        m5.set('g', 0.1)

        # Decorate the 'soma' with (multiple) mechanisms
        decor.paint('"soma"', m1)
        decor.paint('"soma"', m2) # Error: can't place the same mechanism on overlapping regions
        decor.paint('"soma"', m3) # This is ok: m3 is a new, derived mechanism by virtue of
                                  # having a different name, i.e. 'pas/e=-45' vs. 'pas'.

    .. method:: mechanism(name, params)

        constructor for mechanism with *name* and range parameter overrides *params*,
        for example: ``arbor.mechanism(name='pas', params={'g': 0.01})``.

        :param name: name of mechanism.
        :type name: str
        :param params: A dictionary of parameter values, with parameter name as key.
        :type params: dict[str, double]

    .. method:: mechanism(name)
        :noindex:

        constructor for mechanism.
        The *name* can be either the name of a mechanism in the catalogue,
        e.g.  ``arbor.mechanism('pas')``, or an implicitly derived mechanism,
        e.g. ``arbor.mechanism('nernst/k')``.

    .. method:: set(name, value)

        Set new value for a parameter.

        :param name: name of the parameter.
        :type name: str
        :param value: value of the parameter.
        :type value: float

    .. py:attribute:: name
        :type: str

        The name of the mechanism.

    .. py:attribute:: values
        :type: dict

       A dictionary of key-value pairs for the parameters.


.. py:class:: mechanism_info

    Meta data about the fields and ion dependencies of a mechanism.
    The data is presented as read-only attributes.

    .. code-block:: Python

        import arbor
        cat = arbor.default_catalogue()

        # Get mechanism_info for the 'expsyn' mechanism.
        mech = cat['expsyn']

        # Query the mechanism_info for information about parameters.
{'fraction_non_alphanumeric': 0.08860892388451444, 'fraction_numerical': 0.008608923884514435, 'mean_word_length': 2.6275704493526275, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3593683', 'n_tokens_mistral': 2639, 'n_tokens_neox': 2497, 'n_words': 1123}