:py:mod:`neurorosettes.simulation`
==================================

.. py:module:: neurorosettes.simulation

.. autoapi-nested-parse::

   This module deals with the neuron structure and functions



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   neurorosettes.simulation.Timer
   neurorosettes.simulation.Container
   neurorosettes.simulation.Simulation



Functions
~~~~~~~~~

.. autoapisummary::

   neurorosettes.simulation.ccw
   neurorosettes.simulation.intersect



.. py:function:: ccw(A, B, C)


.. py:function:: intersect(A, B, C, D)


.. py:class:: Timer

   Class to store the simulation time data.

   .. py:attribute:: total_time
      :type: float

      The total time of a simulation (in minutes).

   .. py:attribute:: step
      :type: float

      The time between simulation points (in minutes).

   .. py:attribute:: current_time
      :type: float
      :value: 0.0

      The current time point of the simulation.

   .. py:method:: get_progress_bar()

      Returns a progress bar with the simulation time



.. py:class:: Container(grid, simulation_2d, neuron_factory, contact_factory, drag_coefficient = 10.0, density_check = None)

   Class that represents the environment where neurons exist.

   :param grid: The grid where simulation objects will be stored,
                to improve neighbor interactions.
   :param simulation_2d: If the simulation is 2D or 3D.
   :param neuron_factory: The factory object to be used to create new neurons.
   :param contact_factory: The factory object to be used to create interactions.
   :param drag_coefficient: The drag coefficient of the extracellular space.
   :param density_check: Optional contact inhibition function to inhibit proliferation
                         when the cell density is too high.

   .. py:method:: set_density_check(density_check)

      Sets the contact inhibition function to be used before proliferation.

      :param density_check: The contact inhibition function to be used.


   .. py:method:: register_neuron(neuron, color='gray')

      Registers a neuron and its representation into the container.

      :param neuron: The new neuron to be registered.
      :param color: The color of the sphere that will represent the new neuron
                    in the renderings of the simulation.


   .. py:method:: update_drawings()

      Updates the representations of the neurons


   .. py:method:: advance_cycles(time_step)

      Updates the biological clocks of every object in the simulation.

      :param time_step: The time between simulation time points.


   .. py:method:: create_new_neuron(coordinates, outgrowth_axis = None, color='darkblue')

      Creates a new neuron and registers it to the container's grid.

      The new neuron is created as an undifferentiated cell body centred at
      the passed coordinates. An outgrowth axis vector can be passed to model
      neurite outgrowth along this direction.

      :param coordinates: The center position of the neuron's cell body.
      :param outgrowth_axis: The direction of growth of the neuron's neurites.
      :param color: The color of the new neurite in the simulation renders.


   .. py:method:: differentiate()

      Checks for neurons that are flagged for differentiation and deals with differentiation


   .. py:method:: kill()

      Checks for neurons that are flagged for death and removes them from the container


   .. py:method:: divide()

      Checks for neurons that are flagged for division and deals with division


   .. py:method:: get_displacement_from_force(force, time_step)

      Returns the displacemnt value that a force originates, based on the equation of motion.

      :param force: The force value to be converted to a displacement
      :param time_step: The time passed between simulation time points.


   .. py:method:: move_cell(neuron, new_coordinates)

      Moves the cell to a new position and updates the proximal point of the first neurite.

      :param neuron: The neuron object to be moved.
      :param new_coordinates: The new coordinates to be assigned to the cell body's centre.


   .. py:method:: move_neurite(neurite, new_coordinates)

      Deals with moving a neurite's distal point and updating it on the grid.

      :param neurite: The neurite object to be moved.
      :param new_coordinates: The new coordinates to be assigned to the neurite's distal point.


   .. py:method:: compute_displacements(time_step)

      Computes the displacement for each object based on the resulting force.

      :param time_step: The time passed between simulation time points.


   .. py:method:: update_cell_positions()

      Updates the positions of all the simulation objects based on their velocity.


   .. py:method:: solve_mechanics(time_step)

      Solves the mechanical interactions and updates the neurons' positions.

      Goes through each object and computes the resulting force acting on
      it, then gets the object's velocity based on the equation of motion.
      When all of the objects are checked, the positions are updated based
      on the calculated velocity.

      :param time_step: The time passed between simulation time points.



.. py:class:: Simulation(timer, container)

   Class to create and run a simulation.

   :param timer: The structure to store the time data of the simulation.
   :param container: The structure to store the spatial data of the simulation.

   .. py:method:: run()

      Runs the entire simulation by solving the mechanics at each time point.


   .. py:method:: save_meshes(file_name)

      Saves the neurons as PLY objects. Cell bodies are saved as spheres.
      Neurites are saved as cylinders.


   .. py:method:: from_file(config_path)
      :classmethod:

      Initializes a Simulation object from a YAML config file.

      :param config_path: The path to the YAML file config file.