Getting Started#

Follow the Installation Guide:

  • Set up a new environment

  • Install the software into the environment

Note

This guide aims to get your first model running with the bare minimum steps. If you’d like to familiarize yourself with the core concepts and get a more top level understanding first, check out the Top Level Guide before you continue.

The framework supports both declarative statements in configuration formats, or Python code. Be sure to take a quick look at each code tab to get a feel for the equivalent forms of configuration coding!

Create a project#

Use the command below to create a new project directory and some starter files:

bsb new my_first_model --quickstart --json
cd my_first_model

The project now contains a couple of important files:

  • network_configuration.json: your components are declared and parametrized here.

  • A pyproject.toml file: your project settings are declared here.

  • A placement.py and connectome.py file to put your code in.

The configuration contains a base_layer, a base_type and an example_placement. These minimal components are enough to compile your first network. You can do this from the CLI or Python:

bsb compile --verbosity 3 --plot

from bsb.core import Scaffold
from bsb.config import from_json
from bsb.plotting import plot_network
import bsb.options

bsb.options.verbosity = 3
config = from_json("network_configuration.json")
network = Scaffold(config)
network.compile()
plot_network(network)

The verbosity flag increases the amount of output that is generated, to follow along or troubleshoot. The plot flags opens a plot 🙂.

Define starter components#

Topology#

Your network model needs a description of its shape, which is called the topology of the network. The topology exists of 2 types of components: Regions and Partitions. Regions combine multiple partitions and/or regions together, in a hierarchy, all the way up to a single topmost region, while partitions are exact pieces of volume that can be filled with cells.

To get started, we’ll add a second layer top_layer, and a region brain_region which will stack our layers on top of each other:

  "regions": {
    "brain_region": {
      "type": "stack",
      "children": ["base_layer", "top_layer"]
    }
  },
  "partitions": {
    "base_layer": {
      "type": "layer",
      "thickness": 100,
      "stack_index": 0
    },
    "top_layer": {
      "type": "layer",
      "thickness": 100,
      "stack_index": 1
    }
  },

config.partitions.add("top_layer", thickness=100, stack_index=1)
config.regions.add(
    "brain_region",
    type="stack",
    children=[
        "base_layer",
        "top_layer",
    ],
)

The type of the brain_region is stack. This means it will place its children stacked on top of each other. The type of base_layer is layer. Layers specify their size in 1 dimension, and fill up the space in the other dimensions. See Introduction for more explanation on topology components.

Cell types#

The CellType is a definition of a cell population. During placement 3D positions, optionally rotations and morphologies or other properties will be created for them. In the simplest case you define a soma radius and density or fixed count:

  "cell_types": {
    "base_type": {
      "spatial": {
        "radius": 2,
        "density": 1e-3
      }
    },
    "top_type": {
      "spatial": {
        "radius": 7,
        "count": 10
      }
    }
  },

config.cell_types.add("top_type", spatial=dict(radius=7, count=10))

Placement#

  "placement": {
    "base_placement": {
      "strategy": "bsb.placement.ParticlePlacement",
      "cell_types": ["base_type"],
      "partitions": ["base_layer"]
    },
    "top_placement": {
      "strategy": "bsb.placement.ParticlePlacement",
      "cell_types": ["top_type"],
      "partitions": ["top_layer"]
    }
  },

config.placement.add(
    "all_placement",
    strategy="bsb.placement.ParticlePlacement",
    cell_types=["base_type", "top_type"],
    partitions=["base_layer"],
)

The placement blocks use the cell type indications to place cell types into partitions. You can use other PlacementStrategies by setting the strategy attribute. The BSB offers some strategies out of the box, or you can implement your own. The ParticlePlacement considers the cells as spheres and bumps them around as repelling particles until there is no overlap between them. The data is stored in PlacementSets per cell type.

Take another look at your network:

bsb compile -v 3 -p --clear

Note

We’re using the short forms -v and -p of the CLI options --verbosity and --plot, respectively. You can use bsb --help to inspect the CLI options.

Warning

We pass the --clear flag to indicate that existing data may be overwritten. See Storage flags for more flags to deal with existing data.

Connectivity#

  "connectivity": {
    "A_to_B": {
      "strategy": "bsb.connectivity.AllToAll",
      "presynaptic": {
        "cell_types": ["base_type"]
      },
      "postsynaptic": {
          "cell_types": ["top_type"]
      }
    }
  }

config.connectivity.add(
    "A_to_B",
    strategy="bsb.connectivity.AllToAll",
    presynaptic=dict(cell_types=["base_type"]),
    postsynaptic=dict(cell_types=["top_type"]),
)

The connectivity blocks specify connections between systems of cell types. They can create connections between single or multiple pre and postsynaptic cell types, and can produce one or many ConnectivitySets.

Regenerate the network once more, now it will also contain your connections! With your cells and connections in place, you’re ready to move to the Simulating networks stage.

What next?

Continue getting started

Follow the rest of the guides and learn how to include morphologies.

Components

Learn how to write your own components to e.g. place or connect cells.

Simulations

Learn how to simulate your network models

Examples

View examples explained step by step

Plugins

Learn to package your code for others to use!

Contributing

Help out the project by contributing code.

Recap#

{
  "name": "Starting example",
  "storage": {
    "engine": "hdf5",
    "root": "network.hdf5"
  },
  "network": {
    "x": 400.0,
    "y": 600.0,
    "z": 400.0
  },
  "regions": {
    "brain_region": {
      "type": "stack",
      "children": ["base_layer", "top_layer"]
    }
  },
  "partitions": {
    "base_layer": {
      "type": "layer",
      "thickness": 100,
      "stack_index": 0
    },
    "top_layer": {
      "type": "layer",
      "thickness": 100,
      "stack_index": 1
    }
  },
  "cell_types": {
    "base_type": {
      "spatial": {
        "radius": 2,
        "density": 1e-3
      }
    },
    "top_type": {
      "spatial": {
        "radius": 7,
        "count": 10
      }
    }
  },
  "placement": {
    "base_placement": {
      "strategy": "bsb.placement.ParticlePlacement",
      "cell_types": ["base_type"],
      "partitions": ["base_layer"]
    },
    "top_placement": {
      "strategy": "bsb.placement.ParticlePlacement",
      "cell_types": ["top_type"],
      "partitions": ["top_layer"]
    }
  },
  "connectivity": {
    "A_to_B": {
      "strategy": "bsb.connectivity.AllToAll",
      "presynaptic": {
        "cell_types": ["base_type"]
      },
      "postsynaptic": {
          "cell_types": ["top_type"]
      }
    }
  }
}

from bsb.core import Scaffold
from bsb.config import from_json
from bsb.plotting import plot_network
import bsb.options

bsb.options.verbosity = 3
config = from_json("network_configuration.json")

config.partitions.add("top_layer", thickness=100, stack_index=1)
config.regions.add(
    "brain_region",
    type="stack",
    children=[
        "base_layer",
        "top_layer",
    ],
)
config.cell_types.add("top_type", spatial=dict(radius=7, count=10))
config.placement.add(
    "all_placement",
    strategy="bsb.placement.ParticlePlacement",
    cell_types=["base_type", "top_type"],
    partitions=["base_layer"],
)
config.connectivity.add(
    "A_to_B",
    strategy="bsb.connectivity.AllToAll",
    presynaptic=dict(cell_types=["base_type"]),
    postsynaptic=dict(cell_types=["top_type"]),
)

network = Scaffold(config)
network.compile()
plot_network(network)