digger.analyze.energetics

Module Contents

Functions

energetics

Analyze a series of fixed grid output to generate energetics information.

API

digger.analyze.energetics.energetics(wdir: str = '.', output_type: str = 'fgout', gdir: str = '_output', csvout: str = 'energetics.csv', mthresh: float = 0.3, gravity: float = 9.81, phi: float = 38.0, rho_s: float = 2700, rho_f: float = 1000, drytolerance: float = 0.001, sealevel: float = 0, east: float = None, west: float = None, south: float = None, north: float = None, plot: float = True, plot_tmax: float = 60, bing: bool = False, epsg: int = None, yaml_out: str = 'energetics.yaml') → dict

Analyze a series of fixed grid output to generate energetics information.

For this analysis, the domain is broken up into the region containing landslide material (solid volume fraction greater than mthresh) and the region containing not-landslide material*.

This function will generate two files:

• The file specified by csvout contains time-series information about total masses, center of mass locations, and energy components (kinetic and potential) at each output timestep.

• The file specified by yaml_out contains a summary based on analyzing the above time series (e.g., peak kinetic energy, initial potential energy). The contents of this yaml file are also returned by the function.

Diagnostic plots are optionally created.

Much of the analysis was inspired by that presented in Iverson and George (2016).

Inputs:

wdirstr

Working directory within which D-Claw was run. This directory is expected to contain the standard .data files associated with a clawpack run.

output_typestr

Type of gridded output. Options are "fgout", indicating clawpack fgout-style output that will be read using the xarray FGOutBackend. Alternatively, "netcdf4" indicates netcdf files.

If output_type=="fgout", then an installation of the clawpack python modules is necessary as they provide the xarray FGOutBackend. To meet this requirement, install D-Claw as described in the documentation.

netcdfs are expected to have the variables for depth (h), surface elevation (eta), depth times x-directed velocity (hu), depth times y-directed velocity (hv), and depth times solid fraction (hm).

If bing==True then hm is not used and it is assumed that all material is landslide material.

gdirstr

The name of the directory within wdir that contains the gridded output files.

csvoutstr

The path, relative to the current directory to place time-variable results. See below for a description of all columns within csvout.

mthreshfloat

The threshold value of m that demarcates landslide material from not-landslide material.

gravityfloat

Gravitational acceleration in mks units.

phifloat

Friction angle in degrees.

rho_sfloat

Density of the solid fraction in mks units.

rho_ffloat

Density of the fluid in mks units.

drytolerancefloat

The minimum thickness of material considered.

sealevelfloat

The value of sea level used in the simulation. This is necessary to calculate potential energy of a flat sea level as zero.

eastfloat

The energetics analysis may be restricted in space by specifying a bounding box with extent (west, east, south, north). Should no values for any of these optional parameters be used, the entire domain of the gridded files is used.

westfloat

The western extent of the restricted area of interest.

southfloat

The southern extent of the restricted area of interest.

northfloat

The northern extent of the restricted area of interest.

plotbool

Whether to generate diagnostic plots (not publication quality).

plot_tmaxfloat

The maximum time to plot.

bingbool

Whether the results are from a Bingclaw simulation (this functionality is preliminary).

epsgint

The EPSG code of the simulation.

yaml_outstr

The name of a file within wdir where the contents of out_info will be placed as a yaml file.

Outputs:

out_info, dict

out_info contains the following columns:

Table 5 Returned dictionary key value definition.

Key	Description of value	Units
PE0	Initial potential energy of landslide material	joules
KEmax	Maximum kinetic energy of landslide material	joules
velmax	Maximum velocity of landslide material	meters per second
initial_mass	Initial mass of landslide material	kilograms
initial_volume	Initial volume of lanslide material	meters cubed
initial_density	Initial density of landslide material	kilograms per meter cubed
initial_m	Initial solid volume fraction of landslide material	unitless
center_of_mass_fall_height	Fall height of the landslide center of mass	meters
center_of_mass_distance	Travel distance of the landslide center of mass (along the travel path)	meters
h_over_l	Landslide fall height over travel distance	unitless
l_over_h	Landslide travel distance over fall height	unitless
KEmax_over_PE0	Maximum kinetic energy over initial potential energy.	unitless
A_over_V_23	Maximum area impacted by landslide material divided by initial landslide volume to the 2/3 power	unitless

This function will generate a file called ‘energetics.csv’. It will have one row per fixed grid output timestep and the following columns:

Table 6 Columns in energetics.csv.

Column name	Column description	Units
time	Simulation time	seconds
ls_com_x	X-coordinate of the landslide center of mass	meters
ls_com_y	Y-coordinate of the landslide center of mass	meters
ls_com_z	Z-coordinate of the landslide center of mass	meters
not_com_x	X-coordinate of the not-landslide material center of mass	meters
not_com_y	Y-coordinate of the not-landslide material center of mass	meters
not_com_z	Z-coordinate of the not-landslide material center of mass	meters
ls_vel_x	X-directed landslide center of mass velocity	meters per second
ls_vel_y	Y-directed landslide center of mass velocity	meters per second
ls_vel_z	Z-directed landslide center of mass velocity	meters per second
ls_vel_mag	Magnitude of landslide center of mass velocity	meters per second
not_vel_x	X-directed not-landslide center of mass velocity	meters per second
not_vel_y	Y-directed not-landslide center of mass velocity	meters per second
not_vel_z	Z-directed not-landslide center of mass velocity	meters per second
not_vel_mag	Magnitude of not-landslide center of mass velocity	meters per second
ls_acc_x	X-directed landslide acceleration	meters per second squared
ls_acc_y	Y-directed landslide acceleration	meters per second squared
ls_acc_z	Z-directed landslide acceleration	meters per second squared
not_acc_x	X-directed not-landslide acceleration	meters per second squared
not_acc_y	Y-directed not-landslide acceleration	meters per second squared
not_acc_z	Z-directed not-landslide acceleration	meters per second squared
moving_mass_ls	Moving mass of landslide material	kilograms
Moving_mass_not	Moving mass of not-landslide material	kilograms
total_mass_ls	Total mass of landslide material	kilograms
total_mass_not	Total mass of not-landslide material	kilograms
total_vol_ls	Total volume of landslide material	cubic meters
total_area_ls	Total area covered by landslide material	square meters
ls_mean_density	Mean density of landslide material	kilograms per meter cubed
ls_mean_m	Mean solid fraction of landslide material	unitless,
ls_PE	Potential energy of landslide material	joules
not_PE	Potential energy of not-landslide material	joules
ls_KE_inst	Instantaneous kinetic energy of landslide material. Calculated by summing the quantity mass times velocity squared of each compuational grid cell	joules
not_KE_inst	Instantaneous kinetic energy of not-landslide material	joules
d_ls_PE_dt	Change in landslide potential energy with time	joules per second
d_not_PE_dt	Change in not-landslide potential energy with time	joules per second
d_ls_KE_inst_dt	Change in landslide instantaneous kinetic energy with time	joules per second
d_not_KE_inst_dt	Change in not-landslide instantaneous kinetic energy with time	joules per second
theta	The local slope instantaneously descended by the landslide center of mass. \(\tan \theta = \frac{dH}{dL}\) where \(H\) is the center of mass fall height and \(L\) is the center of mass travel distance. See the text just before Iverson and George (2016) equation (19).	degrees
ls_KE_com	The kinetic energy of the landslide center of mass.	joules
d_ls_KE_com_dt	The change in the kinetic energy of the landslide center of mass with time.	joules per second
dKE_dPE	The change in landslide instantaneous kinetic energy as a function of the change in landslide potential energy.	unitless
psi	Effective basal friction angle. See Iverson and George (2016) equation (19)	degrees
water_efficiency	The total energy in not-landslide material (instantaneous kinetic energy and potential energy) divided by the initial landslide potential energy.	unitless

References

Iverson, R.M., and George, D.L., 2016, Modelling landslide liquefaction, mobility bifurcation and the dynamics of the 2014 Oso disaster: Geotechnique, v. 66, no. 3, p. 13, https://doi.org/10.1680/jgeot.15.LM.004.