Main Model

Bases: Generic[H, N], Model, _Notice, _States

Base class of a main ABSESpy model.

Attributes:

Name	Type	Description
name	str	name of the model. By default, it's the lowercase of class name. E.g.: TestModel -> testmodel.
settings	DictConfig	Structured parameters of the model. Other module or submodules can search the configurations here structurally. For an example, if the settings is a nested DictConfig like {'nature': {'test': 3}}, users can access the parameter 'test = 3' by model.nature.params.test.
human	Union[H, BaseHuman]	The Human module.
nature	Union[N, BaseNature]	The nature module.
time	TimeDriver	Time driver.
params	DictConfig	Parameters of the model, having another alias .p.
run_id	int | None	The run id of the current model. It's useful in batch run.
agents	_ModelAgentsContainer	The container of all agents. One model only has one specific container where all alive agents are stored.
actors	ActorsList[Actor]	All agents on the earth (added to a specific PatchCell) as a list. A model can create multiple lists referring different actors.

Source code in abses/main.py

def __init__(
    self,
    parameters: DictConfig = DictConfig({}),
    human_class: Optional[Type[H]] = None,
    nature_class: Optional[Type[N]] = None,
    run_id: Optional[int] = None,
    outpath: Optional[Path] = None,
    experiment: Optional[Experiment] = None,
    **kwargs: Optional[Any],
) -> None:
    Model.__init__(self, **kwargs)
    _Notice.__init__(self)
    _States.__init__(self)
    self._exp = experiment
    self._run_id: Optional[int] = run_id
    self.outpath = cast(Path, outpath)
    self._settings = DictConfig(parameters)
    self._setup_logger(parameters.get("log", {}))
    self.running: bool = True
    self._breeds: Dict[str, Type[Actor]] = {}
    self._containers: List[_AgentsContainer] = []
    self._version: str = __version__
    self._check_subsystems(h_cls=human_class, n_cls=nature_class)
    self._agents = _ModelAgentsContainer(
        model=self, max_len=kwargs.get("max_agents", None)
    )
    self._time = TimeDriver(model=self)
    self.schedule: BaseScheduler = BaseScheduler(model=self)
    self.datacollector: ABSESpyDataCollector = ABSESpyDataCollector(
        parameters.get("reports", {})
    )
    self._do_each("initialize", order=("nature", "human"))
    self._do_each("set_state", code=1)  # initial state

exp property

exp

Returns the associated experiment.

outpath property writable

outpath

Output path where to deposit assets.

run_id property

run_id

The run id of the current model. It's useful in batch run. When running a single model, the run id is None.

name property

name

name of the model. By default, it's the class name.

version property

version

Report the current version of this model.

settings property

settings

Structured parameters of the model. Other module or submodules can search the configurations here structurally.

For an example, if the settings is a nested DictConfig like {'nature': {'test': 3}}, users can access the parameter 'test' by both ways: 1. model.nature.params.test. 2. model.nature.p.test.

agents property

agents

The container of all agents. One model only has one specific container where all alive agents are stored. Users can access, manipulate, and create agents by this container:

For instances: 1. model.agents.get() to access all agents. 2. model.agents.new(Actor, num=3) to create 3 agents of Actor. 3. model.agents.register(Actor) to register a new breed of agents to the whole model. 4. model.agents.trigger() to trigger a specific event to all agents.

actors property

actors

All agents on the earth as an ActorList. A model can create multiple lists referring different actors.

human property

human

The Human subsystem.

nature property

nature

The Nature subsystem.

time property

time

The time driver & controller

params property

params

The global parameters of this model.

datasets property

datasets

All datasets in the model.

breeds property writable

breeds

All breeds in the model.

plot cached property

plot

Plotting the model.

run_model

run_model(steps=None)

Start running the model.

In order, the model will go through the following steps: 1. Call model.setup() method. 2. Call model.step() method. 3. Repeating steps, until the end situation is triggered 4. Call model.end() method.

Source code in abses/main.py

def run_model(self, steps: Optional[int] = None) -> None:
    """Start running the model.

    In order, the model will go through the following steps:
    1. Call `model.setup()` method.
    2. Call `model.step()` method.
    3. Repeating steps, until the end situation is triggered
    4. Call `model.end()` method.
    """
    self._setup()
    while self.running is True:
        self.time.go()
        self._step()
        if self.time.tick == steps:
            self.running = False
    self._end()

setup

setup()

Users can custom what to do when the model is setup and going to start running.

Source code in abses/main.py

def setup(self) -> None:
    """Users can custom what to do when the model is setup and going to start running."""

step

step()

A step of the model.

Source code in abses/main.py

def step(self) -> None:
    """A step of the model."""

end

end()

Users can custom what to do when the model is end.

Source code in abses/main.py

def end(self) -> None:
    """Users can custom what to do when the model is end."""

summary

summary(verbose=False)

Report the state of the model.

Source code in abses/main.py

def summary(self, verbose: bool = False) -> pd.DataFrame:
    """Report the state of the model."""
    print(f"Using ABSESpy version: {self.version}")
    # Basic reports
    to_report = {
        "name": self.name,
        "state": self.state,
        "tick": self.time.tick,
    }
    for breed in self.agents:
        to_report[breed] = self.agents.has(breed)
    if verbose:
        to_report["model_vars"] = self.datacollector.model_reporters.keys()
        to_report["agent_vars"] = self.datacollector.agent_reporters.keys()
    return pd.Series(to_report)