.. _configuration:

Configuration
=============

User-specification of ursa is accomplished through modifying the configuration file, ``config.yml``. This file is in `yaml <https://yaml.org/>`_ 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
^^^^^^^^^^^^^^^^^^^^^

.. confval:: fire_id
   :type: ``str``
   :default: User must provide

   Unique name for fire, typically has no spaces.


.. confval:: conda
   :type: ``str``
   :default: ursa-env

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


.. confval:: 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.


.. confval:: buffer
   :type: ``int``
   :default: 6000

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


.. confval:: dem
   :type: ``str`` Filepath to raster file
   :default: 10-m topography downloaded from The National Map.

   Note also that if you provide wildcat output (:confval:`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 :confval:`buffer`.


.. confval:: 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 <https://ghsc.code-pages.usgs.gov/lhp/pfdf/api/data/usgs/tnm/dem.html#load-data>`__.


.. confval:: 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.

.. confval:: 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.

.. confval:: 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) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ volume model (``I_15_SE``), and reference permeability value (``kr``, units of :math:`\mathrm{m}^2`). Ursa will then synthesize these runs into plots and files for each ``I_15``.


.. confval:: I_15s
   :type: ``list``
   :default: [25, 50, 75, 100]

   List of rainfall intensities in milimeters per hour.


.. confval:: I15_SEs
   :type: ``list``
   :default: [-1, 0, 1]

   List of standard errors on the `Gartner and others (2014) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ volume model.


.. confval:: 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) <https://doi.org/10.1098/rspa.2013.0819>`_ 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. 


.. confval:: 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 <https://hydro.nationalmap.gov/arcgis/rest/services/wbd/MapServer>`_ and used.


.. confval:: region_field
   :type: ``str``
   :default: huc12

   It is expected that the file indicated by :confval:`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. 


.. confval:: 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 <https://ghsc.code-pages.usgs.gov/lhp/wildcat/>`_ internally or expect precomputed wildcat outputs. Depending on which option is selected, different input files are required.

.. confval:: 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 :confval:`run_wildcat` to ``False``.


.. confval:: dnbr
   :type: ``str`` **Required input**: Filepath to normanized burn ratio dataset
   :default: User must provide

   
   See the `wildcat configuration entry for dnbr <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-dnbr>`_.


.. confval:: kf
   :type: ``str`` **Required input**: Filepath to soil KF-factor dataset
   :default: User must provide

   See the `wildcat configuration entry for kf <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-kf>`_.


.. confval:: kf_field
   :type: ``str``
   :default: KFFACT

   See the `wildcat configuration entry for kf-field <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-kf_field>`_.

.. confval:: kf_fill
   :type: ``bool`` | ``float`` | ``str`` | ``Path``
   :default: KFFACT

   See the `wildcat configuration entry for kf_fill <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-kf_fill>`_.


.. confval:: evt
   :type: ``str`` Filepath to existing vegetation type dataset
   :default: Dataset will be downloaded from Landfire.

   If no file is provided, the :confval:`evt_version` dataset will be downloaded from `Landfire <https://landfire.gov/>`_.

.. confval:: evt_version
   :type: ``str``
   :default: 240EVT

   The dataset version to be downloaded from `Landfire <https://landfire.gov/>`_.


.. confval:: lfps_email
   :type: ``str``
   :default: No default

   An email address related to the data request. See the `pfdf.data.landfire.read <https://ghsc.code-pages.usgs.gov/lhp/pfdf/api/data/landfire/index.html#pfdf-data-landfire-read>`_ documentation for additional information.


.. confval:: severity
   :type: ``str`` Filepath to BARC4-like burn severity
   :default: No default

   See the `wildcat configuration entry for severity <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-severity>`_.


.. confval:: retainments
   :type: ``str`` Filepath to debris retainment features
   :default: Not used

   See the `wildcat configuration entry for retainments <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-retainments>`_.


.. confval:: 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 <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-excluded>`_.


.. confval:: included
   :type: ``str`` Filepath indicating areas that should be retained during network filtering
   :default: Not used

   See the `wildcat configuration entry for included <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-included>`_.


.. confval:: iswater
   :type: ``str`` Filepath to waterbody mask
   :default: Not used

   See the `wildcat configuration entry for iswater <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-iswater>`_.


.. confval:: isdeveloped
   :type: ``str`` Filepath to human development mask
   :default: Not used

   See the `wildcat configuration entry for isdeveloped <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-isdeveloped>`_.


.. confval:: min_area_km2
   :type: ``float`` 
   :default: 0.02

   See the `wildcat configuration entry for min_area_km2 <https://ghsc.code-pages.usgs.gov/lhp/wildcat/api/config/preprocess.html#confval-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.

.. confval:: smoothed_slope_threshold
   :type: ``float``
   :default: 0.50

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

.. confval:: smoothed_slope_dx
   :type: ``float``
   :default: 50

   Length scale for smoothing the slope.


.. confval:: smoothed_stream_power_threshold
   :type: ``float``
   :default: 15

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

.. confval:: 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 <https://ghsc.code-pages.usgs.gov/lhp/wildcat/commands/assess.html#assessment-results>`_.

.. confval:: basin_file
   :type: ``str`` **Required input**: Filepath to wildcat basin file
   :default: User must provide

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

.. confval:: outlet_file
   :type: ``str`` **Required input**: Filepath to wildcat outlet file
   :default: User must provide

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


.. confval:: segment_file
   :type: ``str`` **Required input**: Filepath to wildcat segment file
   :default: User must provide

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

.. _configuration-IC:

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 :confval:`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.


.. confval:: P_THRESH
   :type: ``float`` 
   :default: 0.5

   Probability threshold for active basins. 

**Selection of the sediment volume model**

.. confval:: sediment_volume_model
   :type: ``str`` 
   :default: g2014

   .. list-table:: Sediment volume options
      :widths: 10 50
      :header-rows: 1

      * - Value
        - Description
      * - ``g2014``
        - Use the `Gartner and others (2014) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_
          emergency assessment model (their equation 3).
          Optionally, also specify a :confval:`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 :confval:`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, :math:`m_0`. 
          This option requires :confval:`m0`.



**Configuration of the Gartner and others (2014) model**

Multiple configuration values provide control over how the `Gartner and others (2014) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ emergency assessment model generates sediment volumes.

First, the pure sediment volume :math:`V_s` is calculated:

.. math::
            V_s = f_g (1-\Phi_g) V_g

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

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

.. confval:: gartner_volume_factor
   :type: ``float`` 
   :default: 1.0

   Factor to apply to the `Gartner and others (2014) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ emergency assessment model.


.. confval:: gartner_porosity
   :type: ``float`` 
   :default: 0.4

   The `Gartner and others (2014) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ 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) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ 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 :math:`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 :math:`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 <https://dpw.lacounty.gov/ldd/lib/fp/Storm%20Drain/LA%20County%20Flood%20Control%20Debris%20Dams%20and%20Basins%20Design%20Manual.pdf>`_

.. _curve-a: https://dpw.lacounty.gov/ldd/lib/fp/Storm%20Drain/LA%20County%20Flood%20Control%20Debris%20Dams%20and%20Basins%20Design%20Manual.pdf

.. confval:: throttle_gartner_volume
   :type: ``bool``
   :default: True

   Flat to indicate whether the volumes produced by the `Gartner and others (2014) <https://doi.org/10.1016/j.enggeo.2014.04.008>`_ emergency assessment model should be throttled.


.. confval:: 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'``.


.. confval:: curve_A_porosity
   :type: ``float``
   :default: 0.3

   Assumed porosity of the material in Curve A.


.. confval:: curve_A_factor
   :type: ``float``
   :default: 1.2

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

.. confval:: 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'``.


.. confval:: 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**


.. confval:: erosion_depth
   :type: ``float`` 
   :default: 0.001

   Erosion depth in units of meters. 

.. confval:: erosion_porosity
   :type: ``float``
   :default: 0.4

   Assumed porosity of eroded material

.. confval:: m0
   :type: ``float`` 
   :default: 0.6

   Initial solid volume content of debris-flow material 

**Selection of the water volume model**

.. confval:: water_volume_model
   :type: ``str`` 
   :default: bulk

   .. list-table:: Water volume options
      :widths: 10 50
      :header-rows: 1

      * - Value
        - Description
      * - ``bulk``
        - Given a specified initial sediment concentration, :confval:`m0` (unitless),
          calculate the total volume of water needed such that when combined with
          the specified volume of sediment (:math:`V_s`), the concentration is correct.
      * - ``runoff``
        - Water volume calculated by the following equation:

          .. math::
            V_w = \frac{I_{15}}{4}\frac{1}{1000} A R

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


.. confval:: runoff_factor
   :type: ``float``
   :default: 1.0

   Runoff factor for water volume calculation. 


**Debris placement**

.. confval:: 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).

   .. list-table:: Water volume options
      :widths: 10 50
      :header-rows: 1

      * - Value
        - Description
      * - ``reservoir``
        -  Hypothetical reservoirs are placed in the basins at a location
           with the outlet drainage area multiplied by :confval:`drainage_threshold` using `digger.make.reservoir() <https://ghsc.code-pages.usgs.gov/lhp/digger/src/autodoc2/digger/digger.make.reservoir.html>`_.
      * - ``segment_buffer``
        - The wildcat-derived segments are buffered by the distance provided in :confval:`segment_buffer` and a uniform depth of material is placed within that buffer

**If** ``debris_placement='reservoir'``

.. confval:: drainage_threshold
   :type: ``float`` 
   :default: 0.8

   Drainage area threshold for hypothetical reservoir placement.


.. confval:: 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.


.. confval:: 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.

.. confval:: max_depth_reservoir
   :type: ``float``
   :default: 5.0

   Maximum reservoir depth.



**If** ``debris_placement='segment_buffer'``

.. confval:: 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. 


.. confval:: 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.


.. confval:: 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.

.. confval:: volume_reduction
   :type: ``bool``
   :default: False

   Whether to use a volume reduction file.


.. confval:: 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``.

.. confval:: 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.


.. confval:: dt_out
   :type: ``float`` 
   :default: 15

   Output timestep (seconds) for making diagnostic animations

.. confval:: m_crit
   :type: ``float`` 
   :default: 0.64

   Critical solid volume fraction.


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


.. confval:: coarse_dx
   :type: ``float`` 
   :default: 200

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


.. confval:: dx
   :type: ``float`` 
   :default: 10

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


.. confval:: mxnest
   :type: ``float`` 
   :default: 3

   Number of levels of refinement.

.. confval:: inratx
   :type: ``list`` 
   :default: [5, 4]

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

.. confval:: max1d
   :type: ``int``
   :default: 300

   Max 1D size of any grid.

.. confval:: manning
   :type: ``float``
   :default: 0.025

   Base Manning coefficient.

.. confval:: manning_max
   :type: ``float``
   :default: 0.06

   Maximum Manning coefficient.

.. confval:: dry_tolerance
   :type: ``float``
   :default: 0.01

   Dry tolerance.


.. confval:: extra_topo_files
   :type: ``list``
   :default: []

   If additional topography files beyond that specified by :confval:`dem` or internally constructed by ursa are needed, provide a list of strings here. These files must be `topotype 3 files <https://www.clawpack.org/topo.html>`_ . 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 :confval:`dem`.



Postprocessing
^^^^^^^^^^^^^^

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

.. confval:: plotunits
   :type: ``str`` 
   :default: mm

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

.. confval:: depth_thresh
   :type: ``float``
   :default: 0.0

   Only consider flow that exceeds this depth threshold in postprocessing.


.. confval:: 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.

.. confval:: 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.

.. confval:: user-regions
   :type: ``dict`` 
   :default: Empty

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

   .. code:: yaml

      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``.


.. confval:: 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 <https://www.openstreetmap.org/>`_.

.. confval:: 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 <https://www.openstreetmap.org/>`_.

.. confval:: 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 <https://hydro.nationalmap.gov/arcgis/rest/services/nhd/MapServer>`_.


Parallelization
^^^^^^^^^^^^^^^

.. confval:: setup_source_threads
   :type: ``int``
   :default: 10

   Number of threads used within a call to :py:func:`ursa setup source <ursa.setup.source.main>`. 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.

.. confval:: setup_run_threads
   :type: ``int``
   :default: 4

   Number of threads used within a call to :py:func:`ursa setup dclaw --run run-number <ursa.setup.dclaw_run.main>`. This step is paralellized in that it sets up an independent simulation for each parallel region.

.. confval:: run_dclaw_threads
   :type: ``int``
   :default: 4

   Number of threads used when D-Claw is run by :py:func:`ursa run dclaw <ursa.run.dclaw.main>`. 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.


.. confval:: 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:

.. literalinclude:: ../../../ursa/initialize/assets/config.yml
  :language: yaml