Writing breve Simulations With Python
<< previous | Chapter 4. Writing breve Simulations with "steve" or Python | next >>

## Writing breve Simulations With Python

Starting with breve 2.6, breve simulations can be written using the Python language. This section describes how to use Python with the breve simulation environment. Because Python is a well-established language with excellent documentation and tutorials, this section does not go into much detail on the language itself, and instead focuses on the overall concepts required to write simulations for breve in Python. If you're completely new to Python, you may wish to consult the official Python documentation

The first step in writing breve simulations with Python is to familiarize yourself with the the section called “Overview to breve's Simulation Structure: For All Frontend Languages”, which describes general information about how simulations are structured, for all frontend languages.

Next, you can take a look at a the section called “Python + breve Example: a basic simulation”, in order to see how the breve simulation structure is used with Python. You can also begin looking at the included demos for real-world examples of how Python is used to write simulations.

Finally, you'll want to explore Chapter 17 to learn how to use the features of the breve engine in your simulations. Note that much of the breve documentation is written for the steve language, but that all methods and classes available in steve are also available in Python (with slightly different names). So all steve language examples in this documentation can be applied to Python as well.

### Writing breve-Complient Python Objects

There are a couple of requirements when creating Python objects which can be added to the breve engine.

All Python files to be loaded into breve should import the breve module to gain access to important breve engine functionality. In order for a Python object to be compatible with the breve engine, it must be a subclass of the breve Python module class `breve.Object`. If an object is not a subclass of breve.Object (either directly, or via any of the other built-in breve classes), it will not be visible to the breve engine. The `__init__` method of the class must execute the superclass `__init__` method (`breve.Object.__init__` in this case) before any breve bridge functionality is used.

The following example illustrates a basic Python file with a simple breve-compatible class defined:

    import breve

    class PythonBridgeObject( breve.Object ):
            def __init__( self ):
                    breve.Object.__init__( self )
                    print "Inited Python bridge object"

            def iterate( self ):
                    print "Iterating Python bridge object"
                    breve.Object.iterate( self )

This simple Python object will be visible to the breve engine and will have its iterate method called at each iteration of the breve engine.

### Python + breve Example: a basic simulation

Here's a simple skeleton of how to write a simulation in breve using Python.

This simulation defines two objects: the controller, and an agent. The controller is a required object, and it must be a subclass of Control. It is what is responsible for initializing the simulation. The agent we create here does nothing, but in a normal simulation, we would create multiple agents and specify their behaviors in the "iterate" method.

    import breve

    class myController( breve.Control ):
            def __init__( self ):
                    breve.Control.__init__( self )
                    self.agent = myAgent()
                    print '''simulation started'''

            def iterate( self ):
                    breve.Control.iterate( self )

    class myAgent( breve.Mobile ):
            def __init__( self ):
                    breve.Mobile.__init__( self )
                    print '''created agent'''

            def iterate( self ):
                    # make the agent do something interesting her
                    breve.Control.iterate( self )

    # instantiate the controller to initialize the simulation
    myController()

### breve Class APIs [Python]

The full list of breve class APIs, including documentation for both Python and steve is available Chapter 17.

<< previous | Up | next >>
Chapter 4. Writing breve Simulations with "steve" or Python | Table of Contents | Writing breve Simulations With "steve"