Get started in 5 minutes¶

Get ABSESpy running¶

In progress

This document is a work in progress if you see any errors, or exclusions or have any problems, please get in touch with us.

Assuming you've successfully installed ABSESpy, along with all its dependencies, and properly configured the environment to import the module into your workspace. Running the first blank model that performs no action is straightforward - simply import, initialize, and run...

In [1]:

# %pip install abses

from abses import MainModel

# %pip install abses from abses import MainModel

In [2]:

# Initialize a model instance
model = MainModel()

# You can check state of the model by `.summary()`.
# model.summary()  # Method removed in 0.8.0

# Initialize a model instance model = MainModel() # You can check state of the model by `.summary()`. # model.summary() # Method removed in 0.8.0

In [3]:

# run it for 5 steps.
model.run_model(steps=5)

# run it for 5 steps. model.run_model(steps=5)

ABSESpy two basic modules¶

As the name "socio-ecological system" suggests, models usually include two basic subsystems (submodules): human and natural. They can be accessed through attributes model.human and model.nature.

In the default model MainModel built by ABSESpy, they are BaseNature and BaseHuman.

In [4]:

type(model.human)

type(model.human)

Out[4]:

abses.human.human.BaseHuman

In [5]:

type(model.nature)

type(model.nature)

Out[5]:

abses.space.nature.BaseNature

The default BaseNature and BaseHuman classes can be used to build custom classes that better reflect the needs of a particular application. In order to use a custom module must be passed to the MainModel constructor as keyword arguments human and nature.

In [6]:

from abses import BaseNature, BaseHuman


class Nature(BaseNature):
    """A custom Nature module."""

    def step(self):
        print(f"Nature in the step {self.time.tick}")


class Human(BaseHuman):
    """A custom Human module."""

    def step(self):
        print(f"Human in the step  {self.time.tick}")

from abses import BaseNature, BaseHuman class Nature(BaseNature): """A custom Nature module.""" def step(self): print(f"Nature in the step {self.time.tick}") class Human(BaseHuman): """A custom Human module.""" def step(self): print(f"Human in the step {self.time.tick}")

In [7]:

model = MainModel(human_class=Human, nature_class=Nature)

model.run_model(steps=3)

model = MainModel(human_class=Human, nature_class=Nature) model.run_model(steps=3)

Nature in the step 1
Human in the step  1
Nature in the step 2
Human in the step  2
Nature in the step 3
Human in the step  3

ABSESpy will also log certain messages to allow a better, real-time understanding of the model's progression.

In [8]:

from abses import Actor, MainModel


class MyActor(Actor):
    """A customized actor"""

    def say_hi(self) -> str:
        print(f"Hello, world! I'm a new {self.breed}!")


model = MainModel()
actors = model.agents.new(Actor, 5)
my_actor = model.agents.new(MyActor, singleton=True)

my_actor.say_hi()
print(model.agents)

from abses import Actor, MainModel class MyActor(Actor): """A customized actor""" def say_hi(self) -> str: print(f"Hello, world! I'm a new {self.breed}!") model = MainModel() actors = model.agents.new(Actor, 5) my_actor = model.agents.new(MyActor, singleton=True) my_actor.say_hi() print(model.agents)

2025-10-15 21:19:11.502 | DEBUG    | abses.agents.container:new:252 - <Handling [5]Agents for MainModel> created 5 Actor.

2025-10-15 21:19:11.503 | DEBUG    | abses.agents.container:new:252 - <Handling [6]Agents for MainModel> created 1 MyActor.

Hello, world! I'm a new MyActor!
<Handling [6]Agents for MainModel>

In [9]:

from abses import MainModel, Actor


class MyModel(MainModel):
    """Customized model."""

    def setup(self):
        n_agents = self.params.get("init_agents")
        self.agents.new(Actor, n_agents)

    def step(self):
        # `p` is a shortcut for `params`
        n_agents = self.p.get("n_agents")
        self.agents.new(Actor, n_agents)

    def end(self):
        n_agents = len(self.agents)
        print(f"At step {self.time.tick}, there are {n_agents} actors.")


parameters = {
    "time": {
        "start": "2000-01-01",
        "end": "2003-03-21",
        "months": 8,
        "years": 2,
    },
    "model": {"init_agents": 5, "n_agents": 1},
}
model = MyModel(parameters=parameters)
model.run_model()

from abses import MainModel, Actor class MyModel(MainModel): """Customized model.""" def setup(self): n_agents = self.params.get("init_agents") self.agents.new(Actor, n_agents) def step(self): # `p` is a shortcut for `params` n_agents = self.p.get("n_agents") self.agents.new(Actor, n_agents) def end(self): n_agents = len(self.agents) print(f"At step {self.time.tick}, there are {n_agents} actors.") parameters = { "time": { "start": "2000-01-01", "end": "2003-03-21", "months": 8, "years": 2, }, "model": {"init_agents": 5, "n_agents": 1}, } model = MyModel(parameters=parameters) model.run_model()

2025-10-15 21:19:11.512 | DEBUG    | abses.agents.container:new:252 - <Handling [5]Agents for MyModel> created 5 Actor.

2025-10-15 21:19:11.513 | DEBUG    | abses.agents.container:new:252 - <Handling [6]Agents for MyModel> created 1 Actor.

At step 1, there are 6 actors.

In [10]:

model  # .summary(verbose=True)  # Method removed in 0.8.0

model # .summary(verbose=True) # Method removed in 0.8.0

Out[10]:

<[v0] MyModel(NEW)>