blocksnet.preprocessing.land_use_optimizer

Classes

`BlocksSchema`(args, *kwargs)	Schema for validating blocks GeoDataFrame.
`LandUseOptimizer`(blocks[, verbose])	Optimizes the allocation of land use within a set of urban blocks.

class blocksnet.preprocessing.land_use_optimizer.BlocksSchema(*args, **kwargs)[source]

Bases: BaseSchema

Schema for validating blocks GeoDataFrame.

Variables:: _geom_types (list) – List of allowed geometry types for the blocks, default is [shapely.Polygon].

class Config

Bases: Config

name = 'BlocksSchema'

class blocksnet.preprocessing.land_use_optimizer.LandUseOptimizer(blocks: GeoDataFrame, verbose: bool = True)[source]

Bases: object

Optimizes the allocation of land use within a set of urban blocks.

Parameters:

blocks (gpd.GeoDataFrame) – GeoDataFrame containing the urban blocks with geometry.
verbose (bool, optional) – If True, progress is displayed using tqdm (default is True).

static _split_polygon(polygon) → GeometryCollection[source]

Splits a polygon into two parts by cutting along its midpoint.

Parameters:: polygon (shapely.Polygon) – The polygon to split.
Returns:: A collection of geometries resulting from the split operation.
Return type:: shapely.GeometryCollection

static _is_block_large(block_geometry: Polygon) → bool[source]

Determines if a block is too large based on its area and aspect ratio.

Parameters:: block_geometry (shapely.Polygon) – The geometry of the block to evaluate.
Returns:: True if the block exceeds size or aspect ratio constraints, False otherwise.
Return type:: bool

classmethod _split_large_blocks(blocks_gdf: GeoDataFrame)[source]

Splits blocks in the GeoDataFrame that are too large according to predefined rules.

Parameters:: blocks_gdf (gpd.GeoDataFrame) – The GeoDataFrame containing block geometries.
Returns:: Updated GeoDataFrame with large blocks split into smaller ones.
Return type:: gpd.GeoDataFrame

classmethod _get_adjacency_graph(blocks_gdf: GeoDataFrame, buffer: float = 10)[source]

Generates an adjacency graph of blocks based on their spatial proximity.

Parameters:

blocks_gdf (gpd.GeoDataFrame) – The GeoDataFrame of blocks with geometries.
buffer (float, optional) – Buffer size used for detecting intersections (default is BUFFER_MIN).

Returns:

A NetworkX graph representing the adjacency relations between blocks.

Return type:

nx.Graph

_generate_initial_X() → dict[int, blocksnet.models.land_use.LandUse][source]

Generates an initial configuration of land uses for the blocks.

Returns:: A dictionary mapping block IDs to initial land uses (default is LandUse.RECREATION).
Return type:: dict[int, LandUse]

static _perturb(X: dict[int, blocksnet.models.land_use.LandUse]) → dict[int, blocksnet.models.land_use.LandUse][source]

Perturbs the current land use configuration by randomly changing the land use of one block.

Parameters:: X (dict[int, LandUse]) – Current land use configuration.
Returns:: Modified configuration with one randomly changed land use.
Return type:: dict[int, LandUse]

_check_adj_rules(X: dict[int, blocksnet.models.land_use.LandUse]) → bool[source]

Validates the adjacency rules for the given land use configuration.

Parameters:: X (dict[int, LandUse]) – Land use configuration to check.
Returns:: True if the configuration satisfies adjacency rules, False otherwise.
Return type:: bool

_check_area_ranges(X: dict[int, blocksnet.models.land_use.LandUse])[source]

Validates that each block’s area falls within the allowed range for its land use.

Parameters:: X (dict[int, LandUse]) – Land use configuration to check.
Returns:: True if all areas are within valid ranges, False otherwise.
Return type:: bool

_check_ratio_ranges(X: dict[int, blocksnet.models.land_use.LandUse])[source]

Checks whether the aspect ratio of each block falls within the allowed range for its land use.

Parameters:: X (dict[int, LandUse]) – Land use configuration to check.
Returns:: True if all aspect ratios are valid, False otherwise.
Return type:: bool

to_shares_dict(X: dict[int, blocksnet.models.land_use.LandUse]) → DataFrame[source]

Converts the land use configuration to a dictionary of land use area shares.

Parameters:: X (dict[int, LandUse]) – Land use configuration.
Returns:: A dictionary mapping each land use to its share of the total area.
Return type:: pd.DataFrame

to_gdf(X: dict[int, blocksnet.models.land_use.LandUse]) → GeoDataFrame[source]

Converts the land use configuration into a GeoDataFrame with land use labels.

Parameters:: X (dict[int, LandUse]) – Land use configuration.
Returns:: GeoDataFrame with land use assignments.
Return type:: gpd.GeoDataFrame

_objective(X: dict[int, blocksnet.models.land_use.LandUse], lu_shares: dict[blocksnet.models.land_use.LandUse, float]) → float[source]

Computes the objective function value, which measures deviation from target land use shares.

Parameters:

X (dict[int, LandUse]) – Land use configuration.
lu_shares (dict[LandUse, float]) – Target land use shares.

Returns:

Sum of squared deviations between actual and target land use shares.

Return type:

float

run(lu_shares: dict[blocksnet.models.land_use.LandUse, float], rate: float = 0.99, t_max: float = 100, t_min: float = 0.001, max_iter=10000) → tuple[source]

Runs the optimization algorithm to find the optimal land use configuration.

Parameters:

lu_shares (dict[LandUse, float]) – Target shares for each land use, must sum to 1.
rate (float, optional) – Cooling rate for the simulated annealing algorithm (default is 0.99).
t_max (float, optional) – Initial temperature for simulated annealing (default is 100).
t_min (float, optional) – Minimum temperature for simulated annealing (default is 1e-3).
max_iter (int, optional) – Maximum number of iterations for the optimization (default is 10000).

Returns:

A tuple containing the best land use configuration, best objective value, list of configurations, and list of objective values.

Return type:

tuple