Bases: BaseSubSystem, GeoSpace, NatureSystemProtocol

Base class for managing spatial components in an ABSESpy model.

This class serves as a container for different raster layers (PatchModules). It is not a raster layer itself, but manages multiple PatchModule instances.

Attributes:

Name	Type	Description
major_layer	Optional[BaseModule]	Primary raster layer of the model. Defaults to first created layer.
total_bounds	Optional[BaseModule]	Spatial extent of the model's area of interest.
crs	CRS	Coordinate Reference System used by the nature module.
layers	CRS	Collection of all managed raster layers.
modules	dict[str, BaseModule]	Factory for creating and managing PatchModules.

Note

By default, an initialized ABSESpy model will create an instance of BaseNature as its 'nature' module.

Parameters:

Name	Type	Description	Default
model	MainModelProtocol	Parent model instance this nature module belongs to.	required
name	str	Name identifier for this module (defaults to "nature").	'nature'

Source code in abses/space/nature.py

def __init__(self, model: MainModelProtocol, name: str = "nature") -> None:
    """Initializes a new BaseNature instance.

    Args:
        model: Parent model instance this nature module belongs to.
        name: Name identifier for this module (defaults to "nature").
    """
    GeoSpace.__init__(self, crs=DEFAULT_CRS)
    BaseSubSystem.__init__(self, model, name=name)

create_module

create_module(
    *args,
    module_cls=PatchModule,
    major_layer=False,
    write_crs=False,
    **kwargs
)

Creates a new raster layer (PatchModule) in this nature module.

Parameters:

Name	Type	Description	Default
module_cls	Type[PatchModule]	Custom PatchModule subclass to instantiate. If None, uses base PatchModule.	PatchModule
major_layer	bool	If True, sets created module as the major layer.	False
write_crs	bool	If True, assigns nature's CRS to module if module's CRS is None.	False
**kwargs	Any	Additional arguments passed to the creation method.	{}

Returns:

Type	Description
PatchModule	Newly created PatchModule instance.

Note

The first created module automatically becomes the major layer. The module is automatically added to nature's layers collection.

Source code in abses/space/nature.py

def create_module(
    self,
    *args: Any,
    module_cls: Type[PatchModule] = PatchModule,
    major_layer: bool = False,
    write_crs: bool = False,
    **kwargs: Any,
) -> PatchModule:
    """Creates a new raster layer (PatchModule) in this nature module.

    Args:
        module_cls: Custom PatchModule subclass to instantiate. If None, uses base PatchModule.
        major_layer: If True, sets created module as the major layer.
        write_crs: If True, assigns nature's CRS to module if module's CRS is None.
        **kwargs: Additional arguments passed to the creation method.

    Returns:
        Newly created PatchModule instance.

    Note:
        The first created module automatically becomes the major layer.
        The module is automatically added to nature's layers collection.
    """
    # Create the module directly with the unified API
    module = super().create_module(
        module_cls=module_cls,
        *args,
        **kwargs,
    )

    if major_layer is True:
        self.major_layer = module
    self.convert_crs(module, write_crs=write_crs)
    if module not in self.layers:
        self.add_layer(module)
    return module

convert_crs

convert_crs(module, write_crs=True)

Convert the CRS of a module to the space's CRS.

Parameters:

Name	Type	Description	Default
module	PatchModule	The module to convert the CRS of.	required
write_crs	bool	If True, sets the module's CRS to the space's CRS.	True

Returns:

Type	Description
	The module with the converted CRS.

Source code in abses/space/nature.py

def convert_crs(self, module: PatchModule, write_crs: bool = True):
    """Convert the CRS of a module to the space's CRS.

    Args:
        module: The module to convert the CRS of.
        write_crs: If True, sets the module's CRS to the space's CRS.

    Returns:
        The module with the converted CRS.
    """
    if module.name not in self.modules:
        raise ValueError(f"{module} is not in {self}.")
    if module.crs is None:
        if write_crs:
            module.crs = self.crs
        else:
            raise ValueError(
                f"{module.name}'s default CRS is None.Space CRS is {self.crs}.",
            )
    return module