====================================================================
Tutorial 4: 複数のポピュレーションからなるネットワーク
====================================================================

概要
====

このチュートリアルでは、複数のニューロンタイプからなる複数ポピュレーションのシミュレーションを行います。

.. seealso::
   対応するBMTKチュートリアル: `Tutorial: Multi-Population Recurrent Network <https://alleninstitute.github.io/bmtk/tutorials/tutorial_04_multi_pop.html>`_

bionetからbionetliteへの変更
==============================

**変更が必要なのはimport文だけです。** それ以外のコードは完全に同一です。

**変更前（BMTK）:**

.. code-block:: python

   from bmtk.builder.networks import NetworkBuilder

**変更後（bionetlite）:**

.. code-block:: python

   from bionetlite import NeuliteBuilder as NetworkBuilder



生成されるファイル
==================

population.csv
--------------

100個のニューロン（興奮性80個 + 抑制性20個）の情報が含まれます。

connection.csv
--------------

4種類のシナプス接続（E→E、E→I、I→E、I→I）の情報が含まれます。

Neuliteが生成するファイル
=========================

bionetliteは以下のディレクトリ内にファイルを生成します：

**ディレクトリ構造**

.. code-block:: text

   sim_ch04_nl/
   ├── V1_population.csv
   ├── V1_V1_connection.csv
   ├── kernel/
   │   └── config.h
   └── data/
       ├── Scnn1a_473845048_m.swc
       ├── Pvalb_470522102_m.swc
       ├── 472363762_fit.csv
       └── 472912177_fit.csv

V1_population.csv
-----------------

Neulite用のポピュレーションファイル。複数のニューロンタイプが定義されています：

.. code-block:: text

   #n_cell,n_comp,name,swc_file,ion_file
   80,3682,Scnn1a_100,data/Scnn1a_473845048_m.swc,data/472363762_fit.csv
   20,1900,PV_101,data/Pvalb_470522102_m.swc,data/472912177_fit.csv

各行は以下の情報を含みます：

* ``#n_cell``: Number of cells (80 excitatory, 20 inhibitory)
* ``n_comp``: Number of compartments (Scnn1a: 3682, PV: 1900)
* ``name``: Population name
* ``swc_file``: Path to SWC morphology file
* ``ion_file``: Path to ion channel parameter file

V1_V1_connection.csv
--------------------

Neulite用の接続ファイル。ポピュレーション内およびポピュレーション間の全シナプス接続を定義します：

.. code-block:: text

   #pre nid,post nid,post cid,weight,tau_decay,tau_rise,erev,delay,e/i
   0,1,5,5e-05,1.0,3.0,0.0,2,e
   0,1,3351,5e-05,1.0,3.0,0.0,2,e
   0,2,28,5e-05,1.0,3.0,0.0,2,e
   ...

各カラムの意味：

* ``#pre nid``: Presynaptic neuron ID
* ``post nid``: Postsynaptic neuron ID
* ``post cid``: Postsynaptic compartment ID
* ``weight``: Synaptic weight
* ``tau_decay``: Decay time constant
* ``tau_rise``: Rise time constant
* ``erev``: Reversal potential
* ``delay``: Synaptic delay (ms)
* ``e/i``: Excitatory (e) or inhibitory (i)

Neuliteカーネルのビルドと実行
=============================

ステップ1: カーネルソースの展開
-------------------------------

Neuliteのkernelディレクトリの内容をbionetliteが生成したkernelディレクトリにコピーします。config.hはbionetliteが生成済みなので除外します：

.. code-block:: bash

   rsync -av --exclude='config.h' /path/to/neulite/kernel/ sim_ch04_nl/kernel/

ステップ2: カーネルのビルド
---------------------------

kernelディレクトリに移動してビルドします。config.hは既にbionetliteによって生成されています：

.. code-block:: bash

   cd sim_ch04_nl/kernel
   make

ステップ3: バイナリの配置
-------------------------

ビルドしたバイナリファイル ``nl`` を1階層上にコピーします：

.. code-block:: bash

   cp nl ../

ステップ4: シミュレーションの実行
---------------------------------

bionetliteが生成したディレクトリに移動して、シミュレーションを実行します：

.. code-block:: bash

   cd ..
   ./nl V1_population.csv V1_V1_connection.csv

.. note::
   **外部ファイルからの入力について**

   Neuliteは現在、BMTKのチュートリアルで行われている外部ファイルからのスパイク入力をサポートしていません。そのため、このチュートリアルで生成されたファイルを用いたシミュレーションでは、外部入力がなくスパイクが発生しません。

   ネットワークの動作を確認するには、config.hで定常電流入力（I_AMP、I_DELAY、I_DURATION）を設定してください。

シミュレーション結果ファイル
----------------------------

Neuliteカーネル実行後、以下のテキストファイルが生成されます：

**s.dat** - スパイク時刻データ

スペース区切りのテキスト形式で、各行に1つのスパイクイベントを記録：

.. code-block:: text

   Time(ms) NeuronID
   12.5 0
   15.3 15
   18.9 42
   23.1 0
   ...

* 1列目: スパイクが発生した時刻（ms）
* 2列目: スパイクを発生させたニューロンのID（0-79: 興奮性、80-99: 抑制性）

**v.dat** - 膜電位データ

スペース区切りのテキスト形式で、各行に全ニューロンの膜電位を記録：

.. code-block:: text

   Time(ms) Neuron0 Neuron1 ... Neuron99
   0.0 -65.0 -65.0 ... -65.0
   0.1 -64.8 -64.9 ... -65.1
   0.2 -64.6 -64.8 ... -65.0
   ...

* 1列目: 時刻（ms）
* 2列目以降: 各ニューロンのソーマ膜電位（mV）、全100個のニューロン分

.. note::
   興奮性ニューロン（0-79）と抑制性ニューロン（80-99）のデータは同じファイル内に含まれています。

LIFモデルとの混在について
=========================

.. note::
   Tutorial 4には元々LIFモデルのニューロンも含まれますが、bionetliteならびにNeuliteは現在biophysicalニューロンのみに対応しています。

   bionetliteは以下のニューロンタイプに対応しています：

   * ✅ biophysical neurons
   * ❌ point neurons (LIFなど)
   * ❌ Virtual neurons

   そのため、このチュートリアルではbiophysicalニューロンに関連するファイルのみが生成されます。

次のステップ
============

* :doc:`../advanced/allen_v1_model` - 実際の研究モデルでの応用例
* :doc:`../user_guide/basic_usage` - 基本的な使い方
* :doc:`../advanced/specification` - サポートされる機能の詳細