The Builder

Users of the Vivarium framework build simulations with components. Components are Python classes that represent aspects and behaviors of simulants. Components can be leveraged directly from external modules like vivarium_public_health or be user-written and customized. More information about components is available in the component concept note.

The Builder (vivarium.framework.engine.Builder) is created during initialization of a vivarium.framework.engine.SimulationContext. Components use the Builder to access interfaces to interact with the Vivarium framework. Most components should have a setup method, where they register for services and provide information about their structure. For example, a component needing to leverage the simulation clock and step size to determine a numerical effect to apply on each time step, will get the simulation clock and step size though the Builder and will register method(s) to apply the effect (e.g., via vivarium.framework.values.ValuesInterface.register_value_modifier()). Another component, needing to initialize state for simulants at before the simulation begin, might call vivarium.framework.population.manager.PopulationInterface.initializes_simulants() in its setup method to register method(s) that setup the additional state.


  • Short blurb on how client code interacts with the framework to build models. (Users write components. Components must have …. Components register for services and provide info about their structure during setup. Link to more comprehensive documentation about components).

  • What is the setup method. Where does the builder come from. Why does this work? Why can’t I just write my procedural code to build a simulation?

  • Okay, I have a component with a setup method, you’re going to give me the builder, what do I do with it?

    • Then here is the menu of services you can use:

      • randomness (some kind of description. An example. Link to API docs & to more comprehensive conceptual/narrative docs).

      • events

      • etc.

  • Should mention the typing pattern that lets you import the builder and get static analysis to work.

  • Build a very simple sim with a couple of components to illustrate how stuff hangs together.

  • Other things: - All builder interfaces follow a pattern. builder.SYSTEM.METHOD(*args, **kwargs) -> either None or special simulation object whose interface is effectively to be a callable or similar (Randomness streams, lookup tables, population views, pipelines, etc.)