{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Data structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Follow a detailed description of the different features of the library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sinaps as sn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Section\n",
    "\n",
    "The class `Section` represents a section of neuron with uniform physical values\n",
    "\n",
    "The characteristics of a section are :\n",
    "\n",
    "* The length `L` in **μm**\n",
    "* The radius `a` in **μm**\n",
    "* The menbrane capacitance `C_m` in **μF/cm²**\n",
    "* The longitunal resistance `R_l` in **Ohm.cm**\n",
    "* The initial potential `V0` in **mV**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Default parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec0 = sn.Section(name=\"Sample section 1\")\n",
    "sec0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Customized values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sinaps uses the [param](https://param.holoviz.org/) library. You can set custom parameters while creating the object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec1 = sn.Section(L=50,a=2,name=\"Sample section 2\")\n",
    "sec1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also set the attribute values after the object is created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec1.R_l=100\n",
    "sec1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Channels\n",
    "\n",
    "Ion channels can be added to a section.\n",
    "\n",
    "There are two types of channels\n",
    "\n",
    "* Point channels\n",
    "* Density channels\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Density Channels\n",
    "Density channels are used to model channels that are distributed everywhere on a section. The current is given per unit of membrane surface."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Leak Channel\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lc1=sn.channels.LeakChannel()\n",
    "lc1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lc2=sn.channels.LeakChannel(\n",
    "            Veq=10, #mV\n",
    "            G_m= 1 #mS/cm²\n",
    "            )\n",
    "lc2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec0.add_channel(lc1)\n",
    "sec0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Point Channels\n",
    "Point channels are used to model channel in specific location of the section, the given current is in pA (not relative to the section membrane surface)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Constant current"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pc=sn.channels.ConstantCurrent(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec0.add_channel(pc,x = 0) #x relative position inside the section (0-1)\n",
    "sec0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The exhaustive list of implemented channels is described in the [API Reference](api_reference.html#channels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Neuron\n",
    "\n",
    "The class `Neuron` represents a set of sections connected together"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn=sn.Neuron()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn.add_section(sec0,0,1)\n",
    "nrn.add_section(sec1,1,2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The structure of the neuron is stored in the attribute `sections` wich is a Dict with the section as keys and the nodes connected by the section as values (2-tuple) :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn.sections"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Accessing the sections\n",
    "By node index in the neuron structure. For example `nrn[i]` gives all the section connected to node i\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn['Sample section 2']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that if sections have same names (if a part of their name is similar to the used keyname), a list of sections will be returned:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn['Sample section']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can change the parameters of multiples section at once :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn['Sample section'].C_m=1.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Access all the sections :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn[:]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simulation\n",
    "\n",
    "The class simulation is linked to a specific neuron and is used to run voltage propagation simulation and electrodiffusion simulations with some custom spatial and time resolutions.\n",
    "The object is also storing the results of the simulation.\n",
    "\n",
    "The solving is done using the [solve_ivp](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html) function from the scipy library. Arguments from the solve_ivp function can be passed directly to sim.run."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create the simulation with neuron `nrn` and spatial resolution of `20`μm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim=sn.Simulation(nrn,dx=20)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run the simulation for timespan `0 - 300` ms: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim.run((0,300))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Voltage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Acces the results of the simulation, i.e. the potential at each time and position. They are stored in a [pandas](https://pandas.pydata.org/) Dataframe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim.V"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim['Sample section 2'].plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim[:].plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Currents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The currents computed by the simulation environment are stored in a [pandas](https://pandas.pydata.org/) Dataframe. They are positive when they go toward inside.\n",
    "\n",
    "The current can be accessed via their class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim.current(sn.channels.ConstantCurrent)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim.current(sn.channels.ConstantCurrent)['Sample section 1'].hvplot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Getting all the channels in a simulation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "[ch.__name__ for ch in sim.channels]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Species\n",
    "\n",
    "The species are stored in the enum Class `Species`.\n",
    "This specific class is used to make the link in channels definition between currents and species flux.\n",
    "To simulate the concentration of a specific species, one first need to add it to the neuron, specifying the initial concentration and the diffusion coeficient. Ions that can be added through the API are: \n",
    "\n",
    "* Ca: calcium\n",
    "* K: potassium \n",
    "* Na: sodium \n",
    "* Buffer: any species, not charged\n",
    "* Anion: a negatively charged ion\n",
    "* Cation: a positively charger ion "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nrn.add_species(sn.Species.Ca,C0=2E-4, D=0.2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec0.C0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sec1.C0[sn.Species.Ca] = 1E-2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2=sn.Simulation(nrn,dx=20)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Voltage simulation needs to be run first:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2.run((0,100))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then you can run the electro-diffusion simulation. The same way than for voltage simulations, the electro-diffusion simulations are run using the solve-ivp function from the scipy library. solve-ivp arguments can be passed directly to the run_diff function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2.run_diff()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As for the potential, the result of the simulation is stored in a [pandas](https://pandas.pydata.org/) Dataframe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2.C"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2.plot.C(sn.Species.Ca)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If several channels of the same type are defined on a section, sim.plot.I will plot the sum of all the currents."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sim2.plot.C_field(sn.Species.Ca)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}