neurite_element.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// Copyright (C) 2021 CERN & University of Surrey for the benefit of the
// BioDynaMo collaboration. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
//
// See the LICENSE file distributed with this work for details.
// See the NOTICE file distributed with this work for additional information
// regarding copyright ownership.
//
// -----------------------------------------------------------------------------
 
#ifndef NEUROSCIENCE_NEURITE_ELEMENT_H_
#define NEUROSCIENCE_NEURITE_ELEMENT_H_
 
#include <set>
#include <string>
#include <unordered_map>
#include <vector>
 
#include "core/agent/agent.h"
#include "core/interaction_force.h"
#include "core/scheduler.h"
#include "core/shape.h"
#include "core/util/log.h"
#include "core/util/math.h"
#include "core/util/random.h"
#include "neuroscience/neuron_or_neurite.h"
#include "neuroscience/neuron_soma.h"
#include "neuroscience/new_agent_event/neurite_bifurcation_event.h"
#include "neuroscience/new_agent_event/neurite_branching_event.h"
#include "neuroscience/new_agent_event/new_neurite_extension_event.h"
#include "neuroscience/new_agent_event/side_neurite_extension_event.h"
#include "neuroscience/new_agent_event/split_neurite_element_event.h"
#include "neuroscience/param.h"
 
namespace bdm {
namespace neuroscience {
 
class NeuriteElement : public Agent, public NeuronOrNeurite {
  BDM_AGENT_HEADER(NeuriteElement, Agent, 1);
 
 public:
  NeuriteElement();
 
  void Initialize(const NewAgentEvent& event) override;
 
  void Update(const NewAgentEvent& event) override;
 
  const AgentUid& GetUid() const override { return Base::GetUid(); }
 
  Spinlock* GetLock() override { return Base::GetLock(); }
 
  void CriticalRegion(std::vector<AgentPointer<>>* aptrs) override;
 
  Shape GetShape() const override { return Shape::kCylinder; }
 
  std::set<std::string> GetRequiredVisDataMembers() const override;
 
  void SetDiameter(real_t diameter) override;
 
  void SetDensity(real_t density);
 
  const Real3& GetPosition() const override { return position_; }
 
  void SetPosition(const Real3& position) override;
 
  void UpdatePosition();
 
  const Real3& GetMassLocation() const { return mass_location_; }
 
  void SetMassLocation(const Real3& mass_location);
 
  real_t GetAdherence() const { return adherence_; }
 
  void SetAdherence(real_t adherence);
 
  const Real3& GetXAxis() const { return x_axis_; }
  const Real3& GetYAxis() const { return y_axis_; }
  const Real3& GetZAxis() const { return z_axis_; }
 
  real_t GetVolume() const { return volume_; }
 
  real_t GetDiameter() const override { return diameter_; }
 
  real_t GetDensity() const { return density_; }
 
  real_t GetMass() const { return density_ * volume_; }
 
  Real3 OriginOf(const AgentUid& daughter_uid) const override;
 
  StructureIdentifierSWC GetIdentifierSWC() const override;
 
  // TODO(neurites) arrange in order end
 
  void RetractTerminalEnd(real_t speed);
 
  void ElongateTerminalEnd(real_t speed, const Real3& direction);
 
  bool BranchPermitted() const;
 
  NeuriteElement* Branch(real_t new_branch_diameter, const Real3& direction,
                         real_t length = 1.0);
 
  NeuriteElement* Branch(const Real3& direction);
 
  NeuriteElement* Branch(real_t diameter);
 
  NeuriteElement* Branch();
 
  bool BifurcationPermitted() const;
  std::array<NeuriteElement*, 2> Bifurcate(real_t length, real_t diameter_1,
                                           real_t diameter_2,
                                           const Real3& direction_1,
                                           const Real3& direction_2);
 
  std::array<NeuriteElement*, 2> Bifurcate(real_t diameter_1, real_t diameter_2,
                                           const Real3& direction_1,
                                           const Real3& direction_2);
 
  std::array<NeuriteElement*, 2> Bifurcate(const Real3& direction_1,
                                           const Real3& direction_2);
 
  std::array<NeuriteElement*, 2> Bifurcate();
 
  // ***************************************************************************
  //      METHODS FOR NEURON TREE STRUCTURE *
  // ***************************************************************************
 
  // TODO(neurites) documentation
  void RemoveDaughter(const AgentPointer<NeuriteElement>& daughter) override;
 
  // TODO(neurites) add documentation
  void UpdateRelative(const NeuronOrNeurite& old_relative,
                      const NeuronOrNeurite& new_relative) override;
 
  Real3 ForceTransmittedFromDaugtherToMother(const NeuronOrNeurite& mother);
 
  // ***************************************************************************
  //   DISCRETIZATION , SPATIAL NODE, CELL ELEMENT
  // ***************************************************************************
 
  void RunDiscretization() override;
 
  // ***************************************************************************
  //   ELONGATION, RETRACTION, BRANCHING
  // ***************************************************************************
 
  void MovePointMass(real_t speed, const Real3& direction);
 
  void SetRestingLengthForDesiredTension(real_t tension);
  void ChangeVolume(real_t speed);
  void ChangeDiameter(real_t speed);
 
  struct MechanicalForcesFunctor : public Functor<void, Agent*, real_t> {
    const InteractionForce* force;
    NeuriteElement* ne;
    Real3& force_from_neighbors;
    Real3& force_on_my_mothers_point_mass;
    real_t& h_over_m;
    bool& has_neurite_neighbor;
    uint64_t& non_zero_neighbor_force;
 
    MechanicalForcesFunctor(const InteractionForce* force,
                            NeuriteElement* neurite,
                            Real3& force_from_neighbors,
                            Real3& force_on_my_mothers_point_mass,
                            real_t& h_over_m, bool& has_neurite_neighbor,
                            uint64_t& non_zero_neighbor_force)
        : force(force),
          ne(neurite),
          force_from_neighbors(force_from_neighbors),
          force_on_my_mothers_point_mass(force_on_my_mothers_point_mass),
          h_over_m(h_over_m),
          has_neurite_neighbor(has_neurite_neighbor),
          non_zero_neighbor_force(non_zero_neighbor_force) {}
 
    void operator()(Agent* neighbor, real_t squared_distance) override;
  };
 
  // ***************************************************************************
  //   Physics
  // ***************************************************************************
 
  Real3 CalculateDisplacement(const InteractionForce* force,
                              real_t squared_radius, real_t dt) override;
 
  // TODO(neurites) documentation
  void ApplyDisplacement(const Real3& displacement) override;
 
  void UpdateLocalCoordinateAxis();
  void UpdateDiameter();
  void UpdateVolume();
 
  // ***************************************************************************
  //   Coordinates transform
  // ***************************************************************************
 
 
  Real3 TransformCoordinatesGlobalToLocal(const Real3& position) const;
 
  Real3 TransformCoordinatesLocalToGlobal(const Real3& position) const;
 
  Real3 TransformCoordinatesLocalToPolar(const Real3& position) const;
 
  Real3 TransformCoordinatesPolarToLocal(const Real3& position) const;
 
  Real3 TransformCoordinatesPolarToGlobal(
      const std::array<real_t, 2>& position) const;
 
  Real3 TransformCoordinatesGlobalToPolar(const Real3& position) const;
 
  // ***************************************************************************
  //   GETTERS & SETTERS
  // ***************************************************************************
 
  bool IsAxon() const { return is_axon_; }
 
  void SetAxon(bool is_axon) { is_axon_ = is_axon; }
 
  AgentPointer<NeuronOrNeurite>& GetMother() { return mother_; }
 
  const AgentPointer<NeuronOrNeurite>& GetMother() const { return mother_; }
 
  void SetMother(const AgentPointer<NeuronOrNeurite>& mother) {
    mother_ = mother;
  }
 
  const AgentPointer<NeuriteElement>& GetDaughterLeft() const;
 
  void SetDaughterLeft(const AgentPointer<NeuriteElement>& daughter);
 
  const AgentPointer<NeuriteElement>& GetDaughterRight() const;
 
  void SetDaughterRight(const AgentPointer<NeuriteElement>& daughter);
 
  int GetBranchOrder() const { return branch_order_; }
 
  void SetBranchOrder(int branch_order) { branch_order_ = branch_order; }
 
  real_t GetActualLength() const { return actual_length_; }
 
  void SetActualLength(real_t actual_length);
 
  real_t GetRestingLength() const { return resting_length_; }
 
  void SetRestingLength(real_t resting_length);
 
  const Real3& GetSpringAxis() const { return spring_axis_; }
 
  void SetSpringAxis(const Real3& axis);
 
  real_t GetSpringConstant() const { return spring_constant_; }
 
  void SetSpringConstant(real_t spring_constant);
 
  real_t GetTension() const { return tension_; }
 
  void SetTension(real_t tension);
 
  Real3 GetUnitaryAxisDirectionVector() const;
 
  bool IsTerminal() const { return daughter_left_ == nullptr; }
 
  Real3 ProximalEnd() const { return mass_location_ - spring_axis_; }
 
  const Real3& DistalEnd() const { return mass_location_; }
 
  real_t LengthToProximalBranchingPoint() const;
 
  real_t GetLength() const { return actual_length_; }
 
  const Real3& GetAxis() const;
 
  void UpdateDependentPhysicalVariables() override;
 
  friend std::ostream& operator<<(std::ostream& str, const NeuriteElement& n);
 
 protected:
  void Copy(const NeuriteElement& rhs);
 
 private:
  // TODO(lukas) data members same as in cell -> resolve once ROOT-9321 has been
  // resolved
  Real3 mass_location_ = {{0.0, 0.0, 0.0}};
 
  Real3 position_ = {{0.0, 0.0, 0.0}};
 
  real_t volume_;
  real_t diameter_ = 1;
  real_t density_;
  real_t adherence_;
  Real3 x_axis_ = {{1.0, 0.0, 0.0}};
  Real3 y_axis_ = {{0.0, 1.0, 0.0}};
  Real3 z_axis_ = {{0.0, 0.0, 1.0}};
 
  bool is_axon_ = false;
 
  AgentPointer<NeuronOrNeurite> mother_;
 
  AgentPointer<NeuriteElement> daughter_left_;
  AgentPointer<NeuriteElement> daughter_right_;
 
  int branch_order_ = 0;
 
  Real3 force_to_transmit_to_proximal_mass_ = {{0, 0, 0}};
 
  Real3 spring_axis_ = {{0, 0, 0}};
 
  real_t actual_length_ = 1;
 
  real_t tension_;
 
  real_t spring_constant_;
 
  real_t resting_length_;
 
  bool has_neurite_neighbor_ = false;
 
  NeuriteElement* SplitNeuriteElement(real_t distal_portion = 0.5);
 
  void RemoveProximalNeuriteElement();
 
  NeuriteElement* ExtendSideNeuriteElement(real_t length, real_t diameter,
                                           const Real3& direction);
 
  void InitializeNewNeuriteExtension(NeuronSoma* soma, real_t diameter,
                                     real_t phi, real_t theta);
 
  void InitializeNeuriteBifurcation(NeuriteElement* mother, real_t length,
                                    real_t diameter, const Real3& direction);
 
  void InitializeSplitOrBranching(NeuriteElement* other, real_t distal_portion);
 
  void InitializeSideExtensionOrBranching(NeuriteElement* mother, real_t length,
                                          real_t diameter,
                                          const Real3& direction);
};
 
}  // namespace neuroscience
}  // namespace bdm
 
#endif  // NEUROSCIENCE_NEURITE_ELEMENT_H_