Projects help you keep your models organized, safe, and neat! A project is a folder containing:

  • The pyproject.toml Python project settings file: This file uses the TOML syntax to set configuration values for the BSB and any other python tools your project uses.

  • One or more configuration files.

  • One or more network files.

  • Your component code.

You can create projects using the command.


Project settings are contained in the pyproject.toml file.

  • [tools.bsb]: The root configuration section: You can set the values of any Options here.

    • [tools.bsb.links]: Contains the file link definitions.

    • [tools.bsb.links."my_network.hdf5"]: Storage specific file links In this example for a storage object called “my_network.hdf5”

verbosity = 3

morpho = [ "sys", "morphologies.hdf5", "newer",]
config = "auto"

config = [ "sys", "thalamus.json", "always",]

Component code#

It’s best practice to keep all of your component code in a subfolder with the same name as your model. For example, if you’re modelling the cerebellum, create a folder called cerebellum. Inside place an file, so that Python can import code from it. Then you best subdivide your code based on component type, e.g. keep placement strategies in a file called That way, your placement components are available in your model as cerebellum.placement.MyComponent. It will also make it easy to distribute your code as a package!

Version control#

An often overlooked aspect is version control! Version control helps you track every change you make as a version of your code, backs up your code, and lets you switch between versions. The git protocol is currently the most popular version control, combined with providers like GitHub or GitLab.

- This was my previous version
+ This is my new version
This line was not affected

This example shows how version control can track every change you make, to undo work, to try experimental changes, or to work on multiple conflicting features. Every change can be stored as a version, and backed up in the cloud.

Projects come with a .gitignore file, where you can exclude files from being backed up. Cloud providers won’t let neuroscientists upload 100GB network files 😇