.. _CXXmodels:

================
Models structure
================

.. toctree::
   :maxdepth: 1

   devel/branching
   devel/critical
   devel/direction

|name| offers the chance to set different models for neuronal outgrowth.
Models are structured in order to allow the user to enable or discard some
specific properties and then set the relevant biological parameters or use the
defaults.
The table of parameters can be found at the end of this page, under the
:ref:`parameters` subsection.


What are models in |name|?
==========================

For now, models are mostly associated to growth cones.
There are also branching models, but these are not yet covered in the
documentation.

A full growth model is composed by a combination of three modules:

* an *extension* component, modeling the 


Making a new growth model
=========================

To add a new model to |name|, you need to decide on two things:

* a name, for instance "great model"
* the type of feature it implements among:

  - deciding how much the growth cone will grow (extension)
  - setting the probability of going into each of the filopodial direction
    (steering)
  - selecting the actual direction in which the growth cone will go next
    (direction selection).

For this example, our "great model" will implement a new way of *steering* the
growth cone.


Create the files
----------------

The C++ files containing the code for the new model must be placed in
``src/models``.
Since we're creating a steering model, we will name them
``steering_great_model.hpp`` and ``steering_great_model.cpp`` (replace of
course ``steering`` with ``extension`` or ``direction_select`` if your model
deals with those instead).


Create the class
----------------

Inside these files, we will create the class ``GreatSteeringModel`` following
the same structure as visible in the other files containing existing models.
This means that our class:

* inherits from :cpp:class:`SteeringModel`
* defines all the functions mentioned in ``steering_interface.hpp``


Tell the simulator about the new model
--------------------------------------

Full growth models are automatically generated by combining all possible modules
into a extention/steering/direction-selection triplets.

This is performed by the python file ``src/models/models_generator.py``.

To add a new model the, you must:

1. include it in the associated methods list (here ``steering_methods``) as
   ``ModelComponent(method="great-model", filename="steering_great_model.hpp", classname="GreatSteeringModel")``
2. add an associated abbreviation in ``abbrev``, for instance ``"great-model": "gm"``
3. add ``steering_great_model.hpp`` and ``steering_great_model.cpp`` to the list
   of files in ``src/models/CMakeLists.txt``

And that's it, you're done!
Your new model is now available in |name| and should appear in the list returned
by :func:`~dense.get_models`.


Creating neurons and setting parameters
=======================================

In order to simulate a system we need to initialize it, and, likely, we would
like to set our own parameters to override the default described in previous
section.
Let's assume we have 1 only neuron, how to manage many neurons and sets of
parameters is described in another section.

Each neuron can be created with a different growth cone model, and in every
moment these parameters can be overwritten, but it's impossible to change the
model, while is possible to turn off/on the neurite branching model (uniform,
actin wave, van pelt)
It's possible to set the same parameters for dendrites and axon or to specify
them, passing a dictionary with the respective name "axon_params" or
"dendrite_params" to the :func:`~dense.create_neurons` function.
This can also be done during the simulation with
:func:`~dense._pygrowth.set_object_properties`

Parameters are set when kernel is initiated and the process is recursive.
Each neuron is created with a ``StatusMap``, which is a dictionary with all the
non-default parameters, each neuron then set the parameters all its neurites,
which set the parameters for all its growth cone. A similar process happen when
status is set during the simulation.


The models of |name| are implemented in C++

.. doxygenclass:: growth::Neuron
    :members:

.. doxygenclass:: growth::Neurite
    :members:

.. doxygenclass:: growth::ActinWave
    :members:

.. doxygenclass:: growth::Node
    :members:

.. doxygenclass:: growth::GrowthCone
    :members:

.. doxygenclass:: growth::Branch
    :members:


.. _parameters:

Parameters
==========

.. doxygenfile:: libgrowth/growth_names.hpp
    :outline: