4.2. Installation and Configuration¶
The ShakeMap Wiki provides a basic quick-start guide to installing and running ShakeMap v4. The present section is intended to provide supplementary material and additional detail for installing, configuring, and running v4.
4.2.1. Installation¶
The Wiki does a pretty good job of explaining the installation process, which is fairly automated. Here we will just reiterate that things will go most smoothly if you use the bash shell and conda virtual environment. Taking a more manual approach will likely lead to conflicts with system software (ShakeMap runs on Python 3.7 or 3.8, while many systems still use 2.7 as a default) and dependency headaches.
4.2.2. Configuration¶
After running sm_profile
the newly-created profile will have its
config directory populated with a default set of configuration files.
These files should be reviewed by the operator prior to running
ShakeMap. Additionally, the config files sometimes change when the
code is updated and so it is fairly common for errors encountered after
an update to be related to changes in the configs. We hope that the
configs will become more stable as the code matures, however it is
useful to check your configuration files against those in the
directory shakemap/data to make sure that you make any necessary
changes to parameters.
Some internationalization support is included in the making of maps with
the mapping
module. See the products.conf section below.
The configuration files are discussed in the sections below.
4.2.2.1. model.conf¶
model.conf contains configuration options for the way modeling works, such
as the GMPE or GMPEs to use, the location of the Vs30, the IMTs to compute,
and options on where the predictions should be computed (i.e., grid
resolution or a list of site locations). One can make a copy of this
file in an event directory to have event-specific config options.
In the event-specific model.conf it is only necessary to list parameters
that differ from those in the global file. Note that you must include
any section or sub-section indicators for the parameter in question. For
instance, to set the max_deviation
parameter in an event-specific
model.conf file, you would include the lines:
[data]
[[outlier]]
max_deviation = 2.0
One may also create a custom GMPE set in the event-specific model.conf and set the system to use it. For instance:
[gmpe_sets]
[[gmpe_northridge_custom]]
gmpes = active_crustal_california,
weights = 1.0,
weights_larage_dist = None
dist_cutoff = nan
site_gmpes = None
weights_site_gmpes = None
[modeling]
gmpe = gmpe_northridge_custom
4.2.2.2. select.conf¶
select.conf has options for GMPE selection, which are used by
the select
module. Note that if/when the select
module runs, it
creates the file model_select.conf in the event’s current directory,
which overrides the GMPE set in the model.conf file located in the
global config directory, but the config settings in an event-specific
model.conf take precedence over the settings in model_select.conf.
Thus, if there are any event-specific changes to the model.conf,
a sensible approach is to rename model_select.conf to model.conf
and then add any other config options to it.
Please see the Ground Motion Selection section for additional details on how this configuration works.
4.2.2.3. products.conf¶
products.conf holds options for the various ShakeMap products, such as contours, rasters, and maps. Additional explanation is available as comments in the products.conf file.
Of particular interest to some users will be the options for language and possibly fontfamily. These options allow for the maps to be generated in a language other than English. If your language of interest already exists in shakemap/data/mapping then you can specify its extension for the language parameter. You may or may not have to set the fontfamily parameter to support your language of choice – that will depend on your system configuration.
If your language does not appear as one of the options in shakemap/data/mapping, you may make the translations as described in one of the language files (e.g., map_strings.en) and add your new file (with the proper extension – see https://www.iana.org/assignments/language-subtag-registry for a list of options) to shakemap/data/mapping directory, and then use that extension for your language parameter. Please also send us your file so that we can include it in the repository. That way it will be there the next time you update or install the ShakeMap software.
Note that the translations only apply to the products of the mapping
module.
4.2.2.4. gmpe_sets.conf¶
This file defines the GMPE sets that are available to be set in
model.conf. These sets can be as simple as a single GMPE with a
weight of 1.0. The GMPE sets can be selected directly from model.conf,
or a the custom GMPE set created by the select
module can be
selected.
4.2.2.5. modules.conf¶
modules.conf ontrols what GMPEs are available for constructing GMPE sets. Generally, this only needs to be edited if you wish to use a GMPE that is not currently imported. The GMPEs are imported from the OpenQuake Engine hazardlib library.
4.2.2.6. shake.conf¶
This configuration file is only for very general configuration options
relating
to the operation of shake
. It allows the operator to configure additional
repositories of ShakeMap modules (“plugins,” if you will). It also allows
the user to set the modules for automatic runs, using the parameter
autorun_modules. The
general idea is that shake can be run specifying specific modules like this:
shake <event id> module1 module2
But since there are many modules and shake
is often invoked via
automated processes, it is convenient to configure a list of
*utorun_modules that will be used when no module is specified
on the command line, i.e., like this:
shake <event id>
4.2.2.7. logging.conf¶
logging.conf contains options for logging. Most users will likely not need to modify this file unless they wish to change the format of the messages, date/time stamps, or other logging behavior.
4.2.2.8. transfer.conf¶
transfer.conf controls the transfer of ShakeMap products to remote
systems via the
transfer
module. See the documentation within the file itself for
explanation of the available options.
4.2.2.9. migrate.conf¶
This file holds parameters that determine how ShakeMap 3.5 data directories
are migrated to ShakeMap v4-compatible directories via the program
sm_migrate
. This file allows the user to choose which OpenQuake
GMPE should be used in place of the ShakeMap GMPE previously used
for each event.
4.2.3. Downloading and Configuring Vs30 and Topography¶
We provide three files available by FTP at ftp://hazards.cr.usgs.gov/shakemap:
global_vs30.grd – The 30 arcsecond resolution Vs30 data set for the entire globe.
topo_30sec.grd – The 30 arcsecond resolution topography data for the entire globe.
topo_15sec.grd – The 15 arcsecond resolution topography data for the entire globe.
By ‘entire globe’ we mean from 56 degrees south to 84 degrees north latitude.
Note that sm_profile
allows the user to download the 30-arcsecond topo
and Vs30 files as part of the creation of a profile. If sm_profile
is
called with the -a
option, these files will be downloaded automatically
and the profile will be configured to use them.
If you did not have sm_profile
download the grids, you have a choice
of 15 or 30 second resolution topography. 15 second data shows
more detail at small scales, but causes ShakeMap to take significantly
longer to make the various output maps. The ShakeMap system at the National
Earthquake Information Center uses the 30 second data. If you plan to use
the 15 second data, modify the topo file name below to topo_15sec.grd.
Note that these files are somewhat large: the 30-second topo is 238 Mb, the 30-second Vs30 is 582 Mb, and the 15-second topo is 745 Mb.
To download the files, do:
> mkdir [home]/shakemap_data
> mkdir [home]/shakemap_data/vs30
> mkdir [home]/shakemap_data/topo
> cd [home]/shakemap_data/vs30
> curl ftp://hazards.cr.usgs.gov/shakemap/global_vs30.grd -o global_vs30.grd
> cd [home]/shakemap_data/topo
> curl ftp://hazards.cr.usgs.gov/shakemap/topo_30sec.grd -o topo_30sec.grd
By default, the system is configured to find the Vs30 and topography files in the locations described above. To set the paths to other locations or file names:
> cd [home]/shakemap_profiles/[profile]/install/config
Modify model.conf to change the line:
vs30file = <DATA_DIR>/vs30/global_vs30.grd
to the location of your Vs30 data. Similarly, edit products.conf and change the line:
topography = <DATA_DIR>/topo/topo_30sec.grd
to the path to your topography file. Note that ShakeMap completes
the macro <INSTALL_DIR>
for the profile in question, but you may set
the paths to any absolute path on your system.