Getting StartedFirst Simulation (Library)

Your First Simulation (B‑Simulant Library)

This walkthrough runs a complete simulation locally using the B‑Simulant library and the ecology domain pack.

Overview

We’ll use a predator–prey model because:

  • It’s easy to reason about
  • The outputs are intuitive
  • You can extend it later with wiring + additional modules

Step 1: Install the library

Install bsim if you haven’t already:

pip install bsim

Step 2: Write a small script

Create a file like predator_prey.py:

import bsim
from bsim.packs.ecology import Environment, OrganismPopulation, PredatorPreyInteraction, PopulationMonitor
 
world = bsim.BioWorld(solver=bsim.FixedStepSolver())
 
rabbits = OrganismPopulation(species="rabbit", initial_count=100)
foxes = OrganismPopulation(species="fox", initial_count=10)
env = Environment(temperature_c=20.0)
 
predation = PredatorPreyInteraction(
    predator="fox",
    prey="rabbit",
    predation_rate=0.01,
    conversion_efficiency=0.02,
)
 
monitor = PopulationMonitor(window_size=50)
 
wb = bsim.WiringBuilder(world)
wb.add("rabbits", rabbits).add("foxes", foxes).add("env", env).add("predation", predation).add("monitor", monitor)
wb.connect("rabbits.out.population_state", ["predation.in.prey"])
wb.connect("foxes.out.population_state", ["predation.in.predator"])
wb.connect("predation.out.population_state", ["rabbits.in.population_state", "foxes.in.population_state"])
wb.connect("rabbits.out.population_state", ["monitor.in.populations"])
wb.connect("foxes.out.population_state", ["monitor.in.populations"])
wb.apply()
 
print(world.simulate(steps=500, dt=0.1))
print(world.collect_visuals())

Run it:

python predator_prey.py

Step 3: Visualize (optional)

If you want a simple web UI for controls and visuals, use SimUI:

pip install "bsim[ui]"

Then see the SimUI docs: SimUI.

Next Steps

Install LibraryOverview