Updated the Getting Started to avoid NEURON & MR errors (#200)

bsb/cli.py

@@ -99,7 +99,7 @@ def start_cli():
         "-c",
         "--config",
         help="Specify the path of the configuration file.",
-        default="mouse_cerebellum_cortex_noTouch.json",
+        default="network_configuration.json",
     )
     parser.add_argument(
         "-r",

bsb/config.py

@@ -121,7 +121,7 @@ def read_config(self, file=None, stream=None):
         if stream is not None:
             self.read_config_stream(stream)
         else:
-            self.read_config_file(file or "mouse_cerebellum_cortex")
+            self.read_config_file(file)
 
     def read_config_file(self, file):
         # Determine extension of file.
@@ -385,7 +385,7 @@ def load_handler(config_string):
         # Tells the base configuration class how to parse the configuration string
         self._load_handler = load_handler
         if file is None and stream is None:
-            file = "mouse_cerebellum_cortex"
+            file = "network_configuration"
         # Initialize base config class, handling the reading of file/stream to string
         ScaffoldConfig.__init__(self, file=file, stream=stream, **kwargs)
 

docs/source/usage/getting-started.rst

@@ -9,71 +9,62 @@ First steps
 The scaffold provides a simple command line interface (CLI) to compile network
 architectures and run simulations.
 
-Let's try out the most basic command, using the default configuration::
+To start, let's create ourselves a project directory and a template configuration::
 
-  bsb -v=3 compile -x=200 -z=200
+  mkdir my_brain
+  cd my_brain
+  bsb make-config
 
-This should produce prints and generate a timestamped HDF5 file in your current
-directory.
+This should produce a template configuration with a single layer and cell type in it. You
+can generate a network from it using the compile command::
+
+  bsb -c network_configuration.json compile -p
+
+.. note::
+
+	You can leave off the ``-c`` (or ``--config``) flag in this case as
+	``network_configuration.json`` is the default config that ``bsb compile`` will look for.
+	The ``-p`` (or ``--plot``) flag will plot your network afterwards
 
 You can explore the structure of the generated output by analysing it with the
-scaffold shell. Open the scaffold shell like this::
+bsb shell or an HDF5 viewer like HDFCompass or HDFViewer. Open the bsb shell like this::
 
-  scaffold
+  bsb
 
 You can now open and view the output HDF5 file like this::
 
   open hdf5 <name>.hdf5
   view
 
 .. note::
-  By default the output file should be named ``scaffold_network`` followed by
+  By default the output file will be named ``scaffold_network`` followed by
   a timestamp.
 
 This will print out the datasets and attributes in the output file. Most notably
 this should give you access to the cell positions and connections.
 
 See :doc:`/usage/cli` for a full guide.
 
-The scaffold exposes many general circuit builder features through a JSON
-configuration interface. By adapting values in the configuration a wide range
-of networks can be obtained. Extending the cerebellum model with new cell types
-can be achieved simply by adding new cell type and connection configuration
-objects to the configuration file. By building new configuration files the
-placement and connection strategies used to construct the cerebellum scaffold
-model could be leveraged to build any general brain area topology.
-
-You can use the default configuration of the mouse cerebellum as a starting
-point for your own scaffold model::
-
-  scaffold make-config my_config.json
-
-You can modify values in there and create a network from it like so::
-
-  bsb -c=my_config compile -p
-
-Open the configuration file in your favorite editor and reduce the simulation
-volume::
-
-  "network_architecture": {
-    "simulation_volume_x": 400.0, # For local single core 150 by 150 is doable.
-    "simulation_volume_z": 400.0,
+The scaffold exposes many general circuit builder features through a JSON configuration
+interface. By adapting values in the configuration a wide range of networks can be
+obtained. Extending the template coonfiguration with new cell types can be achieved by
+adding new cell type and connection configuration objects to the configuration file.
 
 See :doc:`/configuration` for more on the configuration interface. Complex
 brain scaffolds can be constructed purely using these files, but there might be
 cases where it isn't enough, that's why it's also possible to augment the
-configuration with Python scripting:
+configuration with Python scripting.
 
 ============
 First script
 ============
 
-Although the scaffold package features a CLI that can perform most tasks, its
+Although the scaffold package features a CLI that can perform most tasks, the package's
 primary use case is to be included in scripts that can further customize
 the scaffold with things impossible to achieve using the configuration files.
 
 Let's go over an example first script that creates 5 networks with different
-densities of Purkinje cells.
+densities of ``base_type``.
 
 To use the scaffold in your script you should import the :class:`bsb.core.Scaffold`
 and construct a new instance by passing it a :class:`bsb.config.ScaffoldConfig`.
@@ -85,7 +76,7 @@ keyword argument with a path to the configuration file::
   from bsb.config import JSONConfig
   from bsb.reporting import set_verbosity
 
-  config = JSONConfig(file="my_config.json")
+  config = JSONConfig(file="network_configuration.json")
   set_verbosity(3) # This way we can follow what's going on.
   scaffold = Scaffold(config)
 
@@ -94,36 +85,36 @@ keyword argument with a path to the configuration file::
   a `verbosity` attribute to the root node of the `my_config.json` file to set
   the verbosity.
 
-Let's find the purkinje cell configuration::
+Let's find the ``base_type`` cell configuration::
 
-  purkinje = scaffold.get_cell_type("purkinje_cell")
+  base_type = scaffold.get_cell_type("base_type")
 
 The next step is to adapt the Purkinje cell density each iteration. The location
 of the attributes on the Python objects mostly corresponds to their location in
 the configuration file. This means that::
 
-  "purkinje_cell": {
+  "base_type": {
     "placement": {
-      "planar_density": 0.045,
+      "density": 3.9e-4,
       ...
     },
     ...
   }
 
 will be stored in the Python ``CellType`` object under
-``purkinje.placement.planar_density``::
+``base_type.placement.density``::
 
-  max_density = purkinje.placement.planar_density
+  max_density = base_type.placement.density
   for i in range(5):
-    purkinje.placement.planar_density = i * 20 / 100 * max_density
+    base_type.placement.density = i * 20 / 100 * max_density
     scaffold.compile_network()
 
     scaffold.plot_network_cache()
 
     scaffold.reset_network_cache()
 
 .. warning::
-  If you don't use ``reset_network_cache()`` between ``compile_network()`` calls
+  If you don't use ``reset_network_cache()`` between ``compile_network()`` calls,
   the new cells will just be appended to the previous ones. This might lead to
   confusing results.
 
@@ -136,15 +127,15 @@ Full code example
   from bsb.config import JSONConfig
   from bsb.reporting import set_verbosity
 
-  config = JSONConfig(file="my_config.json")
+  config = JSONConfig(file="network_configuration.json")
   set_verbosity(3) # This way we can follow what's going on.
   scaffold = Scaffold(config)
 
-  purkinje = scaffold.get_cell_type("purkinje_cell")
-  max_density = purkinje.placement.planar_density
+  base_type = scaffold.get_cell_type("base_type_cell")
+  max_density = base_type.placement.density
 
   for i in range(5):
-    purkinje.placement.planar_density = i * 20 / 100 * max_density
+    base_type.placement.density = i * 20 / 100 * max_density
     scaffold.compile_network()
 
     scaffold.plot_network_cache()
@@ -161,7 +152,7 @@ connected to each other according to the specified connection strategies::
   from bsb.core import Scaffold
   from bsb.config import JSONConfig
 
-  config = JSONConfig(file="my_config.json")
+  config = JSONConfig(file="network_configuration.json")
 
   # The configuration provided in the file can be overwritten here.
   # For example:
@@ -172,7 +163,7 @@ connected to each other according to the specified connection strategies::
   scaffold.compile_network()
 
 The configuration object can be freely modified before compilation, although
-values that depend on eachother - e.g. layers in a stack - will not update each
+values that depend on eachother - i.e. layers in a stack - will not update each
 other.
 
 Network simulation