Configuration

User-specification of ursa is accomplished through modifying the configuration file, config.yml. This file is in yaml format.

The template configuration file is placed into a project directory within the config directory as part of initialization.

Important

The user is expected to modify the config file before running ursa on a project.

Configuration file values

This section describes all configuration file values and their defaults. Many configuration values are strings indicating the file path of a file. For files that are not required, leave this value blank to use the default values (do not write ‘None’). All filepaths are relative to the project directory. That is, one directory up from the location of the config.yaml file created by:

ursa initialize <name of project>

General configuration

fire_id
Type:
str
Default:
User must provide

Unique name for fire, typically has no spaces.

conda
Type:
str
Default:
ursa-env

The name of the conda environment into which ursa was installed.

perimeter
Type:
str Required input: Filepath to fire perimeter polygon (shapefile or geojson)
Default:
User must provide

Note the following considerations:

  • All computational will be done in the coordinate reference system of the perimeter.

  • The dem and aoi files must MUST be in the same CRS as the perimeter.

  • Other geospatial files will be internally reprojected (region, all three files used within the exposure block of the configuration file.

  • The coordinate system of the perimeter must have units of meters.

buffer
Type:
int
Default:
6000

Buffer distance around the perimeter to consider in analysis. Units are in meters.

dem
Type:
str Filepath to raster file
Default:
10-m topography downloaded from The National Map.

Note also that if you provide wildcat output (run_wildcat =True) we suggest that you use the DEM provided to wildcat as the DEM input here. This DEM must be large enough to cover the perimeter buffered by the buffer.

dem_resolution
Type:
str
Default:
"1/3 arc-second"

DEM resolution. Must be one of the resolutions supported by pfdf.data.usgs.tnm.dem.read.

aoi
Type:
str Filepath to area of interest polygon (shapefile or geojson)
Default:
No area of interest

Optionally, provide an area of interest file. This file is used as a spatial filter to reduce the area considered. Only basins with outlets located within the area of interest are used.

basemap
Type:
str Filepath to geotif of a basemap
Default:
No area of interest

Optionally, provide a basemap. If not provided, a basemap is downloaded from the USGS National Map.

recurrence
Type:
str Filepath to yaml containing recurrence information for each I_15 value used.
Default:
Determined internally from Atlas 14

This yaml file must have top level keys that list each I_15. Each of these keys should have a dictionary as the value. That dictionary msut contain the key median indicating the median recurrence interval associated with the I_15 in year. This file may be useful when considering locations not covered by Atlas 14.

Numerical experiment set up

The following three configuration values are inside of a block called experiment_params.

Ursa will run one run (composed of one or more simulations) for each combination of rainfall intensity (I_15, units of mm/hr), standard error on the Gartner and others (2014) volume model (I_15_SE), and reference permeability value (kr, units of \(\mathrm{m}^2\)). Ursa will then synthesize these runs into plots and files for each I_15.

I_15s
Type:
list
Default:
[25, 50, 75, 100]

List of rainfall intensities in milimeters per hour.

I15_SEs
Type:
list
Default:
[-1, 0, 1]

List of standard errors on the Gartner and others (2014) volume model.

krs
Type:
list
Default:
[ 1e-8, 1e-9, 1e-10]

List of reference permeability values. Units are square meters. Refer to Iverson and George (2014) for explanation of this value.

Spatial parallelization

Ursa breaks up the simulation domain into distinct simulation regions that may be computed independently. By default ursa will use the 12-digit hydrologic unit polygons (HUC12) as the basis for spatial parallelization. If another spatial basis is prefered, provide a polygon-type vector file with the polygons for parallelization.

region
Type:
str Filepath to region file (shapefile or geojson)
Default:
HUC12 values are downloaded

If not provided, HUC12s will be downloaded from the USGS National Hydrography Dataset and used.

region_field
Type:
str
Default:
huc12

It is expected that the file indicated by region will have a field with the name provided in region_field that will be used a a unique identifier. If ursa handles download of HUC12 polygons it will ensure this requirement is met.

simultaneous
Type:
bool
Default:
True

Ursa may be configured to run a simulation for each region defined in this section (simultaneous=True) or each basin delineated in the hazard assessment as an individual simulation (simultaneous=False).

Hazard assessment

Ursa may be configured to run wildcat internally or expect precomputed wildcat outputs. Depending on which option is selected, different input files are required.

run_wildcat
Type:
bool
Default:
True

Whether ursa runs wildcat internally.

Wildcat inputs

A block titled wildcat_inputs is required if run_wildcat=True. This block includes files passed into wildcat. Not all aspects of wildcat configuration are directly accessible within ursa. If additional configuration are required, run wildcat externally and set run_wildcat to False.

dnbr
Type:
str Required input: Filepath to normanized burn ratio dataset
Default:
User must provide

See the wildcat configuration entry for dnbr.

kf
Type:
str Required input: Filepath to soil KF-factor dataset
Default:
User must provide

See the wildcat configuration entry for kf.

kf_field
Type:
str
Default:
KFFACT

See the wildcat configuration entry for kf-field.

kf_fill
Type:
bool | float | str | Path
Default:
KFFACT

See the wildcat configuration entry for kf_fill.

evt
Type:
str Filepath to existing vegetation type dataset
Default:
Dataset will be downloaded from Landfire.

If no file is provided, the evt_version dataset will be downloaded from Landfire.

evt_version
Type:
str
Default:
240EVT

The dataset version to be downloaded from Landfire.

lfps_email
Type:
str
Default:
No default

An email address related to the data request. See the pfdf.data.landfire.read documentation for additional information.

severity
Type:
str Filepath to BARC4-like burn severity
Default:
No default

See the wildcat configuration entry for severity.

retainments
Type:
str Filepath to debris retainment features
Default:
Not used

See the wildcat configuration entry for retainments.

excluded
Type:
str Filepath indicating areas that should be excluded from network delination. In a break from the use within wildcat, if included is provided, the file-basd exclude mask is modified to not exclude the included locations.
Default:
Not used

See the wildcat configuration entry for excluded.

included
Type:
str Filepath indicating areas that should be retained during network filtering
Default:
Not used

See the wildcat configuration entry for included.

iswater
Type:
str Filepath to waterbody mask
Default:
Not used

See the wildcat configuration entry for iswater.

isdeveloped
Type:
str Filepath to human development mask
Default:
Not used

See the wildcat configuration entry for isdeveloped.

min_area_km2
Type:
float
Default:
0.02

See the wildcat configuration entry for min_area_km2.

In addition to the above wildcat inputs, an ursa-specific terrain-based exclude mask is generated internally. A slope and drainage area raster are used to generate a stream power raster (stream power = slope * sqrt(drainage area)) and both the slope raster and the stream power rasters are smoothed. Then a terrain-based exclude mask is generated that represents the locations where either the smoothed slope is less than the smoothed slope threshold or the smoothed stream power is less than the smoothed stream power threshold.

If included is provided, the terrain-based exclude mask is modified to not exclude the included locations.

smoothed_slope_threshold
Type:
float
Default:
0.50

Threshold for determining the smoothed slope component of the terrain-based exclude mask.

smoothed_slope_dx
Type:
float
Default:
50

Length scale for smoothing the slope.

smoothed_stream_power_threshold
Type:
float
Default:
15

Threshold for determining the smoothed slope component of the terrain-based exclude mask.

smoothed_stream_power_dx
Type:
float
Default:
30

Wildcat results

A block titled wildcat_results is required if run_wildcat=False. Although it is not required that these files are produced by wildcat, it is required that these files have the same column names and format as the files generated by wildcat.

basin_file
Type:
str Required input: Filepath to wildcat basin file
Default:
User must provide

Default location is <wildcat_dir>/assessment/basins.geojson

outlet_file
Type:
str Required input: Filepath to wildcat outlet file
Default:
User must provide

Default location is <wildcat_dir>/assessment/outlets.geojson

segment_file
Type:
str Required input: Filepath to wildcat segment file
Default:
User must provide

Default location is <wildcat_dir>/assessment/segments.geojson

Initial conditions

Initial conditions in Ursa control the following elements of initialization and are specified in a block titled initial_conditions.

  • Which basins are active

  • For active basins, how much sediment and water is mobilized

  • What is the spatial pattern by which the mobilized volume of sediment and water is placed into the simulation domain at the start of a simulation.

Only basins with probability thresholds greater than P_THRESH are considered. Within the active basins, supports three options for calculating the volume of sediment and two methods for calculating the volume of sediment.

P_THRESH
Type:
float
Default:
0.5

Probability threshold for active basins.

Selection of the sediment volume model

sediment_volume_model
Type:
str
Default:
g2014
Table 1 Sediment volume options

Value

Description

g2014

Use the Gartner and others (2014) emergency assessment model (their equation 3). Optionally, also specify a gartner_volume_factor that will be applied to increase or reduce the sediment volume by a constant amount.

constant_depth

Use a constant sediment erosion depth times basin area in square meters. This option requires erosion_depth.

constant_concentration

Use a constant sediment concentration. Given the volume of water calculated for each basin, the sediment volume is calculated to ensure that the volume of sediment divided by the volume of sediment and water equals the sediment concentration, \(m_0\). This option requires m0.

Configuration of the Gartner and others (2014) model

Multiple configuration values provide control over how the Gartner and others (2014) emergency assessment model generates sediment volumes.

First, the pure sediment volume \(V_s\) is calculated:

\[V_s = f_g (1-\Phi_g) V_g\]

Where \(f_g\) is the gartner_volume_factor that permits a user to scale the results up or down, \(\Phi_g\) is the assumed porosity in the emergency assessment model, \(V_g\) is the volume produced by the emergency assessment model.

Under some circumstances, \(V_s\) implies an erosion depth over the basin that is unreasonably large. If throttle_gartner_volume=True, additional calculations reduce the sediment volume.

gartner_volume_factor
Type:
float
Default:
1.0

Factor to apply to the Gartner and others (2014) emergency assessment model.

gartner_porosity
Type:
float
Default:
0.4

The Gartner and others (2014) emergency assessment model provides a sediment volume. A porosity is required for ursa to use the output of the emergency assessment model.

Throttling of the Gartner and others (2014) model

Two options are provided to throttle the Gartner and others (2014) emergency assessment model.

First, a constant value may be used. This value is provided is an unbulked sediment depth (that is, a depth assuming porosity equal to zero). The value of \(V_g\) described above is converted to a sediment depth by dividing by the area of the basin and compared with max_gartner_unbulked_sed_depth. The minimum value is used for the basins.

Second, the Los Angeles Flood Control Distric Debris Dams and Basin Design Manual Debris Production Curve A may be used (Haile, 1979). This curve was derived for unburned watersheds and provides and expression for sediment yield as a function of basin area. This function was digitized for use here.

Because Curve A was developed for unburned basins we permit the use of a curve_A_factor that can adjust the value of Curve A. For a given basin, Curve A and the curve_A_factor are used to estimate the maximum depth of sediment, this depth is adjusted to account for porosity, and then it is compared with \(V_g\).

References

Haile, H.H., 1979, Los Angeles County Flood Control District, Design Manual, Debris Dams and Basins: Los Angeles County Flood Control District, Los Angeles, California, last accessed September 26, 2025, at https://dpw.lacounty.gov/ldd/lib/fp/Storm%20Drain/LA%20County%20Flood%20Control%20Debris%20Dams%20and%20Basins%20Design%20Manual.pdf

throttle_gartner_volume
Type:
bool
Default:
True

Flat to indicate whether the volumes produced by the Gartner and others (2014) emergency assessment model should be throttled.

throttle_gartner_method
Type:
str
Default:
'constant'

The method used to throttle the emergency assessment model. Only used if throttle_gartner_volume=True. Options are 'constant' or 'curveA'.

curve_A_porosity
Type:
float
Default:
0.3

Assumed porosity of the material in Curve A.

curve_A_factor
Type:
float
Default:
1.2

Factor to multiply Curve A by to determine the maximum sediment depth.

max_gartner_unbulked_sed_depth
Type:
float
Default:
0.059

Maximum erosion depth of pure sediment to permit. Only used if throttle_gartner_method='constant'.

max_gartner_unbulked_sed_porosity
Type:
float
Default:
1.0

Assumed porosity of hillslope sediment. Used for plotting if throttle_gartner_method='constant'

Configuration of constant erosion depth

erosion_depth
Type:
float
Default:
0.001

Erosion depth in units of meters.

erosion_porosity
Type:
float
Default:
0.4

Assumed porosity of eroded material

m0
Type:
float
Default:
0.6

Initial solid volume content of debris-flow material

Selection of the water volume model

water_volume_model
Type:
str
Default:
bulk
Table 2 Water volume options

Value

Description

bulk

Given a specified initial sediment concentration, m0 (unitless), calculate the total volume of water needed such that when combined with the specified volume of sediment (\(V_s\)), the concentration is correct.

runoff

Water volume calculated by the following equation:

\[V_w = \frac{I_{15}}{4}\frac{1}{1000} A R\]

Where \(V_{w}\) is the water volume (units of cubic meters), \(I_{15}\) is the 15-minute rainfall intensity for the considered run (units of mm/hr), \(A\) is the basin area in square meters, and \(R\) is the runoff factor given by runoff_factor (unitless). In this mode of operation, the sediment concentration will be internally calculated.
runoff_factor
Type:
float
Default:
1.0

Runoff factor for water volume calculation.

Debris placement

debris_placement
Type:
str
Default:
"segment_buffer"

Two options are supported for specifying the initial placement of debris- flow material (the combined volume of water and sediment).

Table 3 Water volume options

Value

Description

reservoir

Hypothetical reservoirs are placed in the basins at a location with the outlet drainage area multiplied by drainage_threshold using digger.make.reservoir().

segment_buffer

The wildcat-derived segments are buffered by the distance provided in segment_buffer and a uniform depth of material is placed within that buffer

If debris_placement='reservoir'

drainage_threshold
Type:
float
Default:
0.8

Drainage area threshold for hypothetical reservoir placement.

reservoir_coarsen
Type:
float
Default:
1.0

The digger function used to generate the reservoirs allows for the topography to be coarsed before the reservoir is constructed. This is useful when working with DEMs with cell sizes <10 m.

limit_reservoir
Type:
float
Default:
1.0

Steep landscapes and large debris-flow volumes may result in unreasonably tall reservoirs. This may be mitigated (to some extent) by limiting the reservoir depth to a max_reservoir_depth and creating a reservoir with a larger areal footprint.

max_depth_reservoir
Type:
float
Default:
5.0

Maximum reservoir depth.

If debris_placement='segment_buffer'

basin_buffer
Type:
float
Default:
40.0

Basin buffer (meters) used for buffered segment option. Material is not placed within basin_buffer of the basin extent.

segment_buffer
Type:
float
Default:
10.0

Segment buffer (meters) used for buffered segment option. Material is placed within segment_buffer distance of the segment polyline.

max_depth_buffer
Type:
float
Default:
2.5

Maximum depth to place within the buffered segments.

Volume reduction

One might want to reduce the volume in a specific basin. This may be accomodated using a volume reduction file. If this option is used the volume adjustment is taken after any throttling of the emergency assesment model.

The volume specified is assumed to be a total volume reflecting the combination of water and sediment as generated by the above options. The implied sediment concentration is maintained after volume reduction.

volume_reduction
Type:
bool
Default:
False

Whether to use a volume reduction file.

volume_reduction_file
Type:
str
Default:
None

File specifying volume reduction. The expected format is no header, one row per basin, and the format of each row is basin_id: volume_to_reduce_cubic_meters

D-Claw parameters

Additional D-Claw parameters, including those needed to describe the computational mesh, are specified in a block titled dclaw_params.

tfinal
Type:
float
Default:
3600

Longest time a simulation may run in seconds. If no momentum exists before this time, the simulation will stop automatically.

dt_out
Type:
float
Default:
15

Output timestep (seconds) for making diagnostic animations

m_crit
Type:
float
Default:
0.64

Critical solid volume fraction.

The following values describe the computational mesh and must be internally consistent.

coarse_dx
Type:
float
Default:
200

Computational grid cell size for the first level (largest grid cell).

dx
Type:
float
Default:
10

Grid cell size for the highest level (smallest grid cell).

mxnest
Type:
float
Default:
3

Number of levels of refinement.

inratx
Type:
list
Default:
[5, 4]

Refinement ratios. Must be at least mxnest-1 long and must relate coarse_dx to dx.

max1d
Type:
int
Default:
300

Max 1D size of any grid.

manning
Type:
float
Default:
0.025

Base Manning coefficient.

manning_max
Type:
float
Default:
0.06

Maximum Manning coefficient.

dry_tolerance
Type:
float
Default:
0.01

Dry tolerance.

extra_topo_files
Type:
list
Default:
[]

If additional topography files beyond that specified by dem or internally constructed by ursa are needed, provide a list of strings here. These files must be topotype 3 files . This functionality is intended to permit use of higher resolution topography within an area of interest. If higher resolution topography is needed over the entire domain provide a file that covers the entire domain to dem.

Postprocessing

Values that influence postprocessing are specified in a block titled postprocessing.

plotunits
Type:
str
Default:
mm

Use millimeters (mm) or inches (in) for the rainfall intensity units in all plots.

depth_thresh
Type:
float
Default:
0.0

Only consider flow that exceeds this depth threshold in postprocessing.

clip_polygon
Type:
str Filepath to polygon-type shapefile
Default:
Not used

If there are runout areas that should be clipped out as part of postprocessing (e.g., because there is a lake), indicate them with this file.

weight
Type:
bool
Default:
False

Whether to weight each I15 Standard Error value equally (False) or weight based on relative probability (True).

Warning

weight is experimental and is computationally very slow.

user-regions
Type:
dict
Default:
Empty

By default, plots are made of each region described by region. Additional plots may be made for user-specified. The syntax for this file is:

user-regions:
   name:
      xmin: <xmin_value>
      ymin: <ymin_value>
      xmax: <xmax_value>
      ymax: <ymax_value>

Exposure analysis

Values that influence the built in exposure analysis are specified in a block titled exposure.

roads
Type:
str
Default:
Downloaded from Open Street Map

File providing the location of roads (shapefile or geojson) for exposure analysis. Alternatively, this file is automatically downloaded from Open Street Map.

buildings
Type:
str
Default:
Downloaded from Open Street Map

File providing the location of buildings (shapefile or geojson) for exposure analysis. Alternatively, this file is automatically downloaded from Open Street Map.

streams
Type:
str
Default:
Downloaded from the National Hydrography Dataset

File providing the location of streams (shapefile or geojson) for exposure analysis. Alternatatively, this file is downloaded automatically from the National Hydrography Dataset.

Parallelization

setup_source_threads
Type:
int
Default:
10

Number of threads used within a call to ursa setup source. This step is parallelized in that it processes each basin within the simulation domain individually to determine the location of 80% of the drainage area.

setup_run_threads
Type:
int
Default:
4

Number of threads used within a call to ursa setup dclaw --run run-number. This step is paralellized in that it sets up an independent simulation for each parallel region.

run_dclaw_threads
Type:
int
Default:
4

Number of threads used when D-Claw is run by ursa run dclaw. This is equivalent to the number of adaptive mesh grids that may be itegrated simultaneously and is the value passed to the OMP_NUM_THREADS environment variable.

parallel_region_topo_threads
Type:
int
Default:
4

Number of threads used to process the full topography .tif into subsets for faster loading.

Default config file

The default config file is reproduced here:

fire_id:
conda: ursa-env
perimeter:
buffer: 6000
dem:
dem_resolution: '1/3 arc-second'
aoi:
basemap:
recurrence:
experiment_params:
  I_15s:
    - 25
    - 50
    - 75
    - 100
  I15_SEs:
    - -1
    - 0
    - 1
  krs:
    - 1e-8
    - 1e-9
    - 1e-10
region:
region_field: huc12
simultaneous: True
run_wildcat: True
wildcat_inputs:
  dnbr:
  kf:
  kf_field: KFFACT
  kf_fill: True
  evt:
  evt_version: LF2024_EVT
  lfps_email:
  severity:
  retainments:
  excluded:
  included:
  iswater:
  isdeveloped:
  min_area_km2: 0.020
  smoothed_slope_threshold: 0
  smoothed_slope_dx: 50
  smoothed_stream_power_threshold: 0
  smoothed_stream_power_dx: 30
wildcat_results:
  basin_file:
  outlet_file:
  segment_file:
initial_conditions:
  P_THRESH: 0.5
  sediment_volume_model: g2014
  gartner_porosity: 0.4
  gartner_volume_factor: 1.0
  throttle_gartner_volume: True
  throttle_gartner_method: constant
  curve_A_porosity: 0.3
  curve_A_factor: 1.2
  max_gartner_unbulked_sed_depth: 0.059 # 1.2* curveA
  max_gartner_unbulked_sed_porosity: 0.3
  erosion_depth: 0.001 
  erosion_porosity: 0.4
  m0: 0.60 
  water_volume_model: bulk
  runoff_factor: 1.0
  debris_placement: segment_buffer
  reservoir_coarsen: 1
  limit_reservoir: True
  max_depth_reservoir: 5
  drainage_threshold: 0.8
  basin_buffer: 40
  segment_buffer: 10
  max_depth_buffer: 2.5
  volume_reduction: False
  volume_reduction_file: 
dclaw_params:
  tfinal: 3600 
  dt_out: 15 
  m_crit: 0.64 
  coarse_dx: 200 
  dx: 10 
  mxnest: 3 
  inratx: 
    - 5
    - 4
  max1d: 300
  manning: 0.025
  manning_max: 0.06
  dry_tolerance: 0.001
  segregation: 0
  beta_seg: 0.5
  delta_kr_order: 1.0
  chi0: 0.5
  extra_topo_files:
postprocessing:
  depth_thresh: 0.0
  plotunits: mm 
  weight_runs: False
  user-regions:
  clip_polygon:
exposure:
  buildings:
  roads:
  streams:
parallelization:
  setup_source_threads: 10
  setup_run_threads: 4
  run_dclaw_threads: 4
  parallel_region_topo_threads: 4