r.futures.parallelpga
Simulates landuse change using FUTURES (r.futures.simulation) on multiple CPUs in parallel.
Module uses Patch-Growing Algorithm (PGA) to simulate urban-rural landscape structure development.
r.futures.parallelpga [-d] nprocs=integer repeat=integer developed=name subregions=name [subregions_potential=name] output=name [output_series=basename] [output_density=basename] [num_steps=integer] predictors=name [,name,...] devpot_params=name development_pressure=name n_dev_neighbourhood=integer development_pressure_approach=string gamma=float scaling_factor=float demand=name [population_demand=name] discount_factor=float compactness_mean=float compactness_range=float num_neighbors=integer seed_search=string patch_sizes=name [density=name] [density_capacity=name] [redevpot_params=name] [redevelopment_lag=integer] [incentive_power=float] [potential_weight=name] [redistribution_matrix=name] [redistribution_output=name] [hand=name] [hand_percentile=integer] [flood_maps_file=name] [flood_logfile=name] [huc=name] [adaptive_capacity=name] [adaptation=name] [output_adaptation=basename] [depth_damage_functions=name] [ddf_subregions=name] [random_seed=integer] [memory=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.futures.parallelpga nprocs=1 repeat=10 developed=name subregions=name output=name predictors=name devpot_params=name development_pressure=name n_dev_neighbourhood=0 development_pressure_approach=gravity gamma=0.0 scaling_factor=0.0 demand=name discount_factor=0.0 compactness_mean=0.0 compactness_range=0.0 num_neighbors=4 seed_search=probability patch_sizes=name
grass.script.run_command("r.futures.parallelpga", nprocs=1, repeat=10, developed, subregions, subregions_potential=None, output, output_series=None, output_density=None, num_steps=None, predictors, devpot_params, development_pressure, n_dev_neighbourhood, development_pressure_approach="gravity", gamma, scaling_factor, demand, population_demand=None, discount_factor, compactness_mean, compactness_range, num_neighbors=4, seed_search="probability", patch_sizes, density=None, density_capacity=None, redevpot_params=None, redevelopment_lag=None, incentive_power=1, potential_weight=None, redistribution_matrix=None, redistribution_output=None, hand=None, hand_percentile=90, flood_maps_file=None, flood_logfile=None, huc=None, adaptive_capacity=None, adaptation=None, output_adaptation=None, depth_damage_functions=None, ddf_subregions=None, random_seed=None, memory=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.futures.parallelpga", nprocs=1, repeat=10, developed="name", subregions="name", output="name", predictors="name", devpot_params="name", development_pressure="name", n_dev_neighbourhood=0, development_pressure_approach="gravity", gamma=0.0, scaling_factor=0.0, demand="name", discount_factor=0.0, compactness_mean=0.0, compactness_range=0.0, num_neighbors=4, seed_search="probability", patch_sizes="name")
grass.tools.Tools.r_futures_parallelpga(nprocs=1, repeat=10, developed, subregions, subregions_potential=None, output, output_series=None, output_density=None, num_steps=None, predictors, devpot_params, development_pressure, n_dev_neighbourhood, development_pressure_approach="gravity", gamma, scaling_factor, demand, population_demand=None, discount_factor, compactness_mean, compactness_range, num_neighbors=4, seed_search="probability", patch_sizes, density=None, density_capacity=None, redevpot_params=None, redevelopment_lag=None, incentive_power=1, potential_weight=None, redistribution_matrix=None, redistribution_output=None, hand=None, hand_percentile=90, flood_maps_file=None, flood_logfile=None, huc=None, adaptive_capacity=None, adaptation=None, output_adaptation=None, depth_damage_functions=None, ddf_subregions=None, random_seed=None, memory=None, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_futures_parallelpga(nprocs=1, repeat=10, developed="name", subregions="name", output="name", predictors="name", devpot_params="name", development_pressure="name", n_dev_neighbourhood=0, development_pressure_approach="gravity", gamma=0.0, scaling_factor=0.0, demand="name", discount_factor=0.0, compactness_mean=0.0, compactness_range=0.0, num_neighbors=4, seed_search="probability", patch_sizes="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
Parameters
nprocs=integer [required]
Number of processes to run in parallel
Default: 1
repeat=integer [required]
Number of times stochastic simulation is repeated
Default: 10
developed=name [required]
Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
subregions=name [required]
Raster map of subregions
subregions_potential=name
Raster map of subregions used with potential file
If not specified, the raster specified in subregions parameter is used
output=name [required]
State of the development at the end of simulation
output_series=basename
Basename for raster maps of development generated after each step
Name for output basename raster map(s)
output_density=basename
Basename for raster maps of density generated after each step
Name for output basename raster map(s)
num_steps=integer
Number of steps to be simulated
predictors=name [,name,...] [required]
Names of predictor variable raster maps
Listed in the same order as in the development potential table
devpot_params=name [required]
Development potential parameters for each region
Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors). Values are separated by tabs. First line is ignored, so it can be used for header
development_pressure=name [required]
Raster map of development pressure
n_dev_neighbourhood=integer [required]
Size of square used to recalculate development pressure
development_pressure_approach=string [required]
Approaches to derive development pressure
Allowed values: occurrence, gravity, kernel
Default: gravity
gamma=float [required]
Influence of distance between neighboring cells
scaling_factor=float [required]
Scaling factor of development pressure
demand=name [required]
Control file with number of cells to convert
population_demand=name
CSV file with population size to accommodate
discount_factor=float [required]
Discount factor of patch size
compactness_mean=float [required]
Mean value of patch compactness to control patch shapes
compactness_range=float [required]
Range of patch compactness to control patch shapes
num_neighbors=integer [required]
The number of neighbors to be used for patch generation (4 or 8)
Allowed values: 4, 8
Default: 4
seed_search=string [required]
The way location of a seed is determined (1: uniform distribution 2: development probability)
Allowed values: random, probability
Default: probability
patch_sizes=name [required]
File containing list of patch sizes to use
density=name
Raster map of population density
density_capacity=name
Raster map of maximum capacity
redevpot_params=name
CSV file with redevelopment potential parameters for each region
Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors).
redevelopment_lag=integer
Number of steps before redevelopment can happen again in a cell developed during simulation
Allowed values: 1-
incentive_power=float
Exponent to transform probability values p to p^x to simulate infill vs. sprawl
Values > 1 encourage infill, < 1 urban sprawl
Allowed values: 0-10
Default: 1
potential_weight=name
Raster map of weights altering development potential
Values need to be between -1 and 1, where negative locally reduces probability and positive increases probability.
redistribution_matrix=name
Matrix containing probabilities of moving from one subregion to another
redistribution_output=name
Base name for output file containing matrix of pixels moved from one subregion to another
hand=name
Height Above Nearest Drainage raster
hand_percentile=integer
Percentile of HAND values within inundated area for depth estimation
Allowed values: 0-100
Default: 90
flood_maps_file=name
CSV file with (step, return period, map of depth) or (step, map of return period)
flood_logfile=name
CSV file with (step, HUC ID, flood probability)
huc=name
Raster of HUCs
adaptive_capacity=name
Adaptive capacity raster
adaptation=name
Raster map of current adaptations for specific flood return periods (e.g. 5, 20)
Name of input raster map
output_adaptation=basename
Basename for raster maps of adaptation generated after each step
Name for output basename raster map(s)
depth_damage_functions=name
CSV file with depth-damage function
ddf_subregions=name
Subregions raster for depth-damage functions
random_seed=integer
Seed for random number generator
The same seed can be used to obtain same results or random seed can be generated by other means.
memory=float
Memory in GB
-d
Runs each subregion separately
r.futures.simulation runs for each subregion and after all subregions are completed, the results are patched together
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
nprocs : int, required
Number of processes to run in parallel
Default: 1
repeat : int, required
Number of times stochastic simulation is repeated
Default: 10
developed : str, required
Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
Used as: input, raster, name
subregions : str, required
Raster map of subregions
Used as: input, raster, name
subregions_potential : str, optional
Raster map of subregions used with potential file
If not specified, the raster specified in subregions parameter is used
Used as: input, raster, name
output : str, required
State of the development at the end of simulation
Used as: output, raster, name
output_series : str, optional
Basename for raster maps of development generated after each step
Name for output basename raster map(s)
Used as: output, raster, basename
output_density : str, optional
Basename for raster maps of density generated after each step
Name for output basename raster map(s)
Used as: output, raster, basename
num_steps : int, optional
Number of steps to be simulated
predictors : str | list[str], required
Names of predictor variable raster maps
Listed in the same order as in the development potential table
Used as: input, raster, name
devpot_params : str, required
Development potential parameters for each region
Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors). Values are separated by tabs. First line is ignored, so it can be used for header
Used as: input, file, name
development_pressure : str, required
Raster map of development pressure
Used as: input, raster, name
n_dev_neighbourhood : int, required
Size of square used to recalculate development pressure
development_pressure_approach : str, required
Approaches to derive development pressure
Allowed values: occurrence, gravity, kernel
Default: gravity
gamma : float, required
Influence of distance between neighboring cells
scaling_factor : float, required
Scaling factor of development pressure
demand : str, required
Control file with number of cells to convert
Used as: input, file, name
population_demand : str, optional
CSV file with population size to accommodate
Used as: input, file, name
discount_factor : float, required
Discount factor of patch size
compactness_mean : float, required
Mean value of patch compactness to control patch shapes
compactness_range : float, required
Range of patch compactness to control patch shapes
num_neighbors : int, required
The number of neighbors to be used for patch generation (4 or 8)
Allowed values: 4, 8
Default: 4
seed_search : str, required
The way location of a seed is determined (1: uniform distribution 2: development probability)
Allowed values: random, probability
Default: probability
patch_sizes : str, required
File containing list of patch sizes to use
Used as: input, file, name
density : str, optional
Raster map of population density
Used as: input, raster, name
density_capacity : str, optional
Raster map of maximum capacity
Used as: input, raster, name
redevpot_params : str, optional
CSV file with redevelopment potential parameters for each region
Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors).
Used as: input, file, name
redevelopment_lag : int, optional
Number of steps before redevelopment can happen again in a cell developed during simulation
Allowed values: 1-
incentive_power : float, optional
Exponent to transform probability values p to p^x to simulate infill vs. sprawl
Values > 1 encourage infill, < 1 urban sprawl
Allowed values: 0-10
Default: 1
potential_weight : str, optional
Raster map of weights altering development potential
Values need to be between -1 and 1, where negative locally reduces probability and positive increases probability.
Used as: input, raster, name
redistribution_matrix : str, optional
Matrix containing probabilities of moving from one subregion to another
Used as: input, file, name
redistribution_output : str, optional
Base name for output file containing matrix of pixels moved from one subregion to another
Used as: output, file, name
hand : str, optional
Height Above Nearest Drainage raster
Used as: input, raster, name
hand_percentile : int, optional
Percentile of HAND values within inundated area for depth estimation
Allowed values: 0-100
Default: 90
flood_maps_file : str, optional
CSV file with (step, return period, map of depth) or (step, map of return period)
Used as: input, file, name
flood_logfile : str, optional
CSV file with (step, HUC ID, flood probability)
Used as: output, file, name
huc : str, optional
Raster of HUCs
Used as: input, raster, name
adaptive_capacity : str, optional
Adaptive capacity raster
Used as: input, raster, name
adaptation : str, optional
Raster map of current adaptations for specific flood return periods (e.g. 5, 20)
Name of input raster map
Used as: input, raster, name
output_adaptation : str, optional
Basename for raster maps of adaptation generated after each step
Name for output basename raster map(s)
Used as: output, raster, basename
depth_damage_functions : str, optional
CSV file with depth-damage function
Used as: input, file, name
ddf_subregions : str, optional
Subregions raster for depth-damage functions
Used as: input, raster, name
random_seed : int, optional
Seed for random number generator
The same seed can be used to obtain same results or random seed can be generated by other means.
memory : float, optional
Memory in GB
flags : str, optional
Allowed values: d
d
Runs each subregion separately
r.futures.simulation runs for each subregion and after all subregions are completed, the results are patched together
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
nprocs : int, required
Number of processes to run in parallel
Default: 1
repeat : int, required
Number of times stochastic simulation is repeated
Default: 10
developed : str | np.ndarray, required
Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
Used as: input, raster, name
subregions : str | np.ndarray, required
Raster map of subregions
Used as: input, raster, name
subregions_potential : str | np.ndarray, optional
Raster map of subregions used with potential file
If not specified, the raster specified in subregions parameter is used
Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
State of the development at the end of simulation
Used as: output, raster, name
output_series : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Basename for raster maps of development generated after each step
Name for output basename raster map(s)
Used as: output, raster, basename
output_density : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Basename for raster maps of density generated after each step
Name for output basename raster map(s)
Used as: output, raster, basename
num_steps : int, optional
Number of steps to be simulated
predictors : str | list[str], required
Names of predictor variable raster maps
Listed in the same order as in the development potential table
Used as: input, raster, name
devpot_params : str | io.StringIO, required
Development potential parameters for each region
Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors). Values are separated by tabs. First line is ignored, so it can be used for header
Used as: input, file, name
development_pressure : str | np.ndarray, required
Raster map of development pressure
Used as: input, raster, name
n_dev_neighbourhood : int, required
Size of square used to recalculate development pressure
development_pressure_approach : str, required
Approaches to derive development pressure
Allowed values: occurrence, gravity, kernel
Default: gravity
gamma : float, required
Influence of distance between neighboring cells
scaling_factor : float, required
Scaling factor of development pressure
demand : str | io.StringIO, required
Control file with number of cells to convert
Used as: input, file, name
population_demand : str | io.StringIO, optional
CSV file with population size to accommodate
Used as: input, file, name
discount_factor : float, required
Discount factor of patch size
compactness_mean : float, required
Mean value of patch compactness to control patch shapes
compactness_range : float, required
Range of patch compactness to control patch shapes
num_neighbors : int, required
The number of neighbors to be used for patch generation (4 or 8)
Allowed values: 4, 8
Default: 4
seed_search : str, required
The way location of a seed is determined (1: uniform distribution 2: development probability)
Allowed values: random, probability
Default: probability
patch_sizes : str | io.StringIO, required
File containing list of patch sizes to use
Used as: input, file, name
density : str | np.ndarray, optional
Raster map of population density
Used as: input, raster, name
density_capacity : str | np.ndarray, optional
Raster map of maximum capacity
Used as: input, raster, name
redevpot_params : str | io.StringIO, optional
CSV file with redevelopment potential parameters for each region
Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors).
Used as: input, file, name
redevelopment_lag : int, optional
Number of steps before redevelopment can happen again in a cell developed during simulation
Allowed values: 1-
incentive_power : float, optional
Exponent to transform probability values p to p^x to simulate infill vs. sprawl
Values > 1 encourage infill, < 1 urban sprawl
Allowed values: 0-10
Default: 1
potential_weight : str | np.ndarray, optional
Raster map of weights altering development potential
Values need to be between -1 and 1, where negative locally reduces probability and positive increases probability.
Used as: input, raster, name
redistribution_matrix : str | io.StringIO, optional
Matrix containing probabilities of moving from one subregion to another
Used as: input, file, name
redistribution_output : str, optional
Base name for output file containing matrix of pixels moved from one subregion to another
Used as: output, file, name
hand : str | np.ndarray, optional
Height Above Nearest Drainage raster
Used as: input, raster, name
hand_percentile : int, optional
Percentile of HAND values within inundated area for depth estimation
Allowed values: 0-100
Default: 90
flood_maps_file : str | io.StringIO, optional
CSV file with (step, return period, map of depth) or (step, map of return period)
Used as: input, file, name
flood_logfile : str, optional
CSV file with (step, HUC ID, flood probability)
Used as: output, file, name
huc : str | np.ndarray, optional
Raster of HUCs
Used as: input, raster, name
adaptive_capacity : str | np.ndarray, optional
Adaptive capacity raster
Used as: input, raster, name
adaptation : str | np.ndarray, optional
Raster map of current adaptations for specific flood return periods (e.g. 5, 20)
Name of input raster map
Used as: input, raster, name
output_adaptation : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Basename for raster maps of adaptation generated after each step
Name for output basename raster map(s)
Used as: output, raster, basename
depth_damage_functions : str | io.StringIO, optional
CSV file with depth-damage function
Used as: input, file, name
ddf_subregions : str | np.ndarray, optional
Subregions raster for depth-damage functions
Used as: input, raster, name
random_seed : int, optional
Seed for random number generator
The same seed can be used to obtain same results or random seed can be generated by other means.
memory : float, optional
Memory in GB
flags : str, optional
Allowed values: d
d
Runs each subregion separately
r.futures.simulation runs for each subregion and after all subregions are completed, the results are patched together
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.
Raises:
grass.tools.ToolError: When the tool ended with an error.
DESCRIPTION
Since FUTURES model is stochastic, multiple runs are recommended. Tool r.futures.parallelpga is a script for running r.futures.simulation on multiple CPUs. All options of r.futures.simulation are available (except for random seed options which are handled by r.futures.parallelpga).
Option repeat changes the number of times the simulation is repeated with the same settings but different random seed. Option nprocs sets the number of parallel processes to be used, which depends on number of available CPUs. Flag -d switches on parallelization on subregion level. Subregions are split and simulation runs on each subregion individually. This approach is convenient if available memory is not sufficient for the entire study area. However, as each subregion is handled separately, development pressure on the edge of a subregion does not influence its neighbors. This can influence the results in case of significant development happening on the subregion boundary.
REFERENCES
- Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013). FUTURES: Multilevel Simulations of Emerging Urban-Rural Landscape Structure Using a Stochastic Patch-Growing Algorithm. Annals of the Association of American Geographers, 103(4), 785-807. DOI: 10.1080/00045608.2012.707591
- Dorning, M. A., Koch, J., Shoemaker, D. A., & Meentemeyer, R. K. (2015). Simulating urbanization scenarios reveals tradeoffs between conservation planning strategies. Landscape and Urban Planning, 136, 28-39. DOI: 10.1016/j.landurbplan.2014.11.011
- Petrasova, A., Petras, V., Van Berkel, D., Harmon, B. A., Mitasova, H., & Meentemeyer, R. K. (2016). Open Source Approach to Urban Growth Simulation. Int. Arch. Photogramm. Remote Sens. Spatial Inf. Sci., XLI-B7, 953-959. DOI: 10.5194/isprsarchives-XLI-B7-953-2016
- Sanchez, G.M., A. Petrasova, A., M.M. Skrip, E.L. Collins, M.A. Lawrimore, J.B. Vogler, A. Terando, J. Vukomanovic, H. Mitasova, and R.K. Meentemeyer. 2023. Spatially interactive modeling of land change identifies location-specific adaptations most likely to lower future flood risk. Sci Rep 13, 18869. DOI: https://doi.org/10.1038/s41598-023-46195-9
SEE ALSO
FUTURES, r.futures.simulation, r.futures.devpressure, r.futures.potential, r.futures.potsurface, r.futures.demand, r.futures.calib, r.futures.gridvalidation, r.futures.validation, r.sample.category
AUTHORS
Corresponding author: Anna Petrasova, akratoc ncsu edu, Center for Geospatial Analytics, NCSU
Original standalone version: Ross K. Meentemeyer, Wenwu Tang, Monica A. Dorning, John B. Vogler, Nik J. Cunniffe, Douglas A. Shoemaker (Department of Geography and Earth Sciences, UNC Charlotte) Jennifer A. Koch (Center for Geospatial Analytics, NCSU)
Port to GRASS and GRASS-specific additions: Vaclav Petras, NCSU GeoForAll
Development pressure, demand, calibration, validation, preprocessing tools and maintenance: Anna Petrasova, NCSU GeoForAll
Climate forcing submodel:
Anna Petrasova,
NCSU GeoForAll
Georgina Sanchez,
Center for Geospatial Analytics, NCSU
Zoning:
Margaret Lawrimore,
Center for Geospatial Analytics, NCSU
Anna Petrasova,
NCSU GeoForAll
SOURCE CODE
Available at: r.futures.parallelpga source code
(history)
Latest change: Friday Apr 17 16:26:46 2026 in commit bc11ef4