Command Line Interface

The recommended way to interact with LASIF projects is to use the command line interface. It consists of a number of subcommands grouped below the main lasif command. The general usage is quickly explained in this paragraph whilst the remainder of this sections explains all subcommands in greater detail.

The general help can be accessed with the lasif help command.

$ lasif help
####################################################################################################
    LASIF - Large Scale Seismic Inversion Framework  [Version ]
    http://krischer.github.io/LASIF
####################################################################################################

usage: lasif [--help] COMMAND [ARGS]

======== Data Acquisition Functions
                   add_gcmt_events: Selects and adds optimally distributed events from the GCMT catalog.
                    add_spud_event: Add an event from the IRIS SPUD webservice to the project.
...

To access the subcommand specific help append --help to the command.

$ lasif init_project --help
usage: lasif init_project [-h] [--ipdb] folder_path

Create a new project.

positional arguments:
  folder_path  where to create the project

optional arguments:
  -h, --help   show this help message and exit
  --ipdb       If true, a debugger will be launched upon encountering an
               exception. Requires ipdb.

Each command can have a number of positional arguments and some optional arguments. Positional arguments have to be given in the specified order while optional arguments can be passed if needed.

Note

All lasif commands work and use the correct project as long as they are executed somewhere inside a project’s folder structure. It will recursively search the parent directories until it finds a config.xml file. This will then be assumed to be the root folder of the project.

Warning

LASIF employs a number of caches to keep it working fast enough. Information about each waveform, event, and station file for example is stored in the caches. The caches are usually automatically kept up-to-date: As soon as data is modified, deleted, added, … the caches will know about it.

Most commands have a --read_only_caches flag. If that argument is given, the caches will not be rebuilt but whatever is in the caches will be assumed to actually exist. This is useful when executing multiple LASIF commands in parallel. Otherwise some processes might write in parallel to the cash databases which will crash LASIF. Use this flag if you need to but best run $ lasif build_all_caches beforehand and be aware of what it means.

MPI

Some commands can be executed with MPI to speed up their execution. Don’t use too many cores as the problem quickly becomes I/O bounds. For example to run the preprocessing on 16 cores, do

$ mpirun -n 16 lasif preprocess_data 1 GCMT_event_AZORES_ISLANDS

The following commands are MPI-enabled. Attempting to run any other command with MPI will result in an error.:

Command Documentation

In the following all subcommands are documented in detail. The commands are grouped by functionality.


Data Acquisition Functions

Data Acquisition

These functions are used to acquire and archive different types of data usually from webservices.

lasif download_data

usage: lasif download_data [-h] [--ipdb] [--read_only_caches]
                               [--providers PROVIDERS [PROVIDERS ...]]
                               event_name

Download waveform and station data for one event.

Positional Arguments
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--providers FDSN providers to query. Will use all known ones if not set.

lasif add_gcmt_events

usage: lasif add_gcmt_events [-h] [--ipdb] [--read_only_caches]
                                 [--min_year MIN_YEAR] [--max_year MAX_YEAR]
                                 count min_magnitude max_magnitude min_distance

Selects and adds optimally distributed events from the GCMT catalog.

Positional Arguments
count maximum amount of events to add
min_magnitude minimum magnitude off events to add
max_magnitude maximum magnitude off events to add
min_distance The minimum acceptable distance to the next closest event in km.
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--min_year minimum year from which to add events
--max_year maximum year from which to add events

lasif add_spud_event

usage: lasif add_spud_event [-h] [--ipdb] [--read_only_caches] url

Add an event from the IRIS SPUD webservice to the project.

Positional Arguments
url any SPUD momenttensor URL
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

Event Management Functions

Event Management

Function helping in organzing the earthquakes inside a LASIF project.

lasif event_info

usage: lasif event_info [-h] [--ipdb] [--read_only_caches] [-v] event_name

Print information about a single event.

Positional Arguments
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
-v Verbose. Print all contained events.

lasif list_events

usage: lasif list_events [-h] [--ipdb] [--read_only_caches] [--details]
                             [--list]

Print a list of all events in the project.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--details print details of filecounts for all events
--list Show only a list of events. Good for scripting bash.

Iteration Management Functions

Iteration Management

Functions dealing with one or more iterations inside a LASIF project.

lasif select_windows

This function can be used with MPI

usage: lasif select_windows [-h] [--ipdb] [--read_only_caches]
                                iteration_name event_name

Autoselect windows for a given event and iteration combination.

This function works with MPI. Don’t use too many cores, I/O quickly becomes the limiting factor. It also works without MPI but then only one core actually does any work.

Positional Arguments
iteration_name name of the iteration
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif generate_input_files

usage: lasif generate_input_files [-h] [--ipdb] [--read_only_caches]
                                      [--simulation_type {normal_simulation,adjoint_forward,adjoint_reverse}]
                                      iteration_name event_name

Generate the input files for the waveform solver.

TYPE denotes the type of simulation to run. Available types are
  • “normal_simulation”
  • “adjoint_forward”
  • “adjoint_reverse”
Positional Arguments
iteration_name name of the iteration
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--simulation_type {normal_simulation (Default), adjoint_forward, adjoint_reverse} type of simulation to run

lasif calculate_all_adjoint_sources

usage: lasif calculate_all_adjoint_sources [-h] [--ipdb] [--read_only_caches]
                                               iteration_name event_name

Calculates all adjoint sources for a given iteration and event.

Positional Arguments
iteration_name name of the iteration
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif finalize_adjoint_sources

usage: lasif finalize_adjoint_sources [-h] [--ipdb] [--read_only_caches]
                                          iteration_name event_name

Finalize the adjoint sources.

Positional Arguments
iteration_name name of the iteration
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif iteration_status

usage: lasif iteration_status [-h] [--ipdb] [--read_only_caches]
                                  iteration_name

Query the current status of an iteration.

Positional Arguments
iteration_name name of the iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif generate_all_input_files

usage: lasif generate_all_input_files [-h] [--ipdb] [--read_only_caches]
                                          [--simulation_type {normal_simulation,adjoint_forward,adjoint_reverse}]
                                          iteration_name

Generates all input files for a certain iteration.

TYPE denotes the type of simulation to run. Available types are
  • “normal_simulation”
  • “adjoint_forward”
  • “adjoint_reverse”
Positional Arguments
iteration_name name of the iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--simulation_type {normal_simulation (Default), adjoint_forward, adjoint_reverse} type of simulation to run

lasif create_successive_iteration

usage: lasif create_successive_iteration [-h] [--ipdb] [--read_only_caches]
                                             existing_iteration new_iteration

Create an iteration based on an existing one.

It will take all settings in one iteration and transfers them to another iteration. Any comments will be deleted.

Positional Arguments
existing_iteration name of the existing iteration
new_iteration name of the new iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif compare_misfits

This function can be used with MPI

usage: lasif compare_misfits [-h] [--ipdb] [--read_only_caches]
                                 from_iteration to_iteration

Compares the misfit between two iterations. Will only consider windows that are identical in both iterations as the comparision is otherwise meaningless.

Positional Arguments
from_iteration past iteration
to_iteration current iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif preprocess_data

This function can be used with MPI

usage: lasif preprocess_data [-h] [--ipdb] [--read_only_caches]
                                 iteration_name [events [events ...]]

Launch data preprocessing.

This function works with MPI. Don’t use too many cores, I/O quickly becomes the limiting factor. It also works without MPI but then only one core actually does any work.

Positional Arguments
iteration_name name of the iteration
events One or more events. If none given, all will be done.
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif select_all_windows

This function can be used with MPI

usage: lasif select_all_windows [-h] [--ipdb] [--read_only_caches]
                                    iteration_name

Autoselect all windows for a given iteration.

This function works with MPI. Don’t use too many cores, I/O quickly becomes the limiting factor. It also works without MPI but then only one core actually does any work.

Positional Arguments
iteration_name name of the iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif list_iterations

usage: lasif list_iterations [-h] [--ipdb] [--read_only_caches]

Print a list of all iterations in the project.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif create_new_iteration

usage: lasif create_new_iteration [-h] [--ipdb] [--read_only_caches]
                                      iteration_name min_period max_period
                                      {SES3D_4_1,SES3D_2_0,SPECFEM3D_CARTESIAN,SPECFEM3D_GLOBE_CEM}

Create a new iteration.

Positional Arguments
iteration_name name of the iteration
min_period the minimum period of the iteration
max_period the maximum period of the iteration
solver_name {SES3D_4_1, SES3D_2_0, SPECFEM3D_CARTESIAN, SPECFEM3D_GLOBE_CEM} name of the solver
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif migrate_windows

usage: lasif migrate_windows [-h] [--ipdb] [--read_only_caches]
                                 from_iteration to_iteration

Migrates windows from one iteration to the next.

Positional Arguments
from_iteration iteration containing windows
to_iteration iteration windows will be migrated to
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_q_model

usage: lasif plot_q_model [-h] [--ipdb] [--read_only_caches] iteration_name

Plots the Q model for a given iteration.

Positional Arguments
iteration_name name of iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif iteration_info

usage: lasif iteration_info [-h] [--ipdb] [--read_only_caches] iteration_name

Print information about a single iteration.

Positional Arguments
iteration_name name of the iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif launch_misfit_gui

usage: lasif launch_misfit_gui [-h] [--ipdb] [--read_only_caches]

Launch the misfit GUI.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

Misc Functions

Misc

All functions that do not fit in one of the other categories.

lasif debug

usage: lasif debug [-h] [--ipdb] [--read_only_caches] files [files ...]

Print information LASIF can gather from a list of files.

Positional Arguments
files filenames to print debug information about
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif shell

usage: lasif shell [-h] [--ipdb] [--read_only_caches]

Drops you into a shell with an active communicator instance.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif serve

usage: lasif serve [-h] [--ipdb] [--read_only_caches] [--port PORT]
                       [--nobrowser] [--debug] [--open_to_outside]

Launches the LASIF webinterface.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--port Port of the webserver.
--nobrowser Do not open a webbrowser.
--debug Turn on debugging. Implies ‘– nobrowser’.
--open_to_outside By default the website can only be opened from the current computer. Use this argument to access it from any other computer on the network.

lasif tutorial

usage: lasif tutorial [-h] [--ipdb]

Open the tutorial in a webbrowser.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif calculate_constant_q_model

usage: lasif calculate_constant_q_model [-h] [--ipdb] [--read_only_caches]
                                            min_period max_period

Calculate a constant Q model useable by SES3D.

Positional Arguments
min_period minimum period for the constant frequency band
max_period maximum period for the constant frequency band
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

Plotting Functions

Plotting

Functions producing pictures.

lasif plot_events

usage: lasif plot_events [-h] [--ipdb] [--read_only_caches]
                             [--type {map,depth,time}]

Plot all events.

type can be one of:
  • map (default) - a map view of the events
  • depth - a depth distribution histogram
  • time - a time distribution histogram
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--type {map (Default), depth, time} the type of plot. map: beachballs on a map, depth: depth distribution histogram, time: time distribution histogram

lasif plot_event

usage: lasif plot_event [-h] [--ipdb] [--read_only_caches] event_name

Plot a single event including stations on a map.

Positional Arguments
event_name name of the event to plot
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_window_statistics

usage: lasif plot_window_statistics [-h] [--ipdb] [--read_only_caches]
                                        iteration_name

Plot the selected windows.

Positional Arguments
iteration_name name of the iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_model

usage: lasif plot_model [-h] [--ipdb] [--read_only_caches]
                            model_name depth component filename

Directly plot a model to a file.

Useful for scripting LASIF.

Positional Arguments
model_name name of the model
depth the depth at which to plot
component the component to plot
filename Output filename. Use ‘-‘ to not write to a file but directly show the kernel.
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_wavefield

usage: lasif plot_wavefield [-h] [--ipdb] [--read_only_caches]
                                iteration_name event_name

Plots a SES3D wavefield.

Positional Arguments
iteration_name name_of_the_iteration
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_raydensity

usage: lasif plot_raydensity [-h] [--ipdb] [--read_only_caches]
                                 [--plot_stations]

Plot a binned raycoverage plot for all events.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--plot_stations also plot the stations

lasif launch_model_gui

usage: lasif launch_model_gui [-h] [--ipdb] [--read_only_caches]

Launch the model GUI.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_windows

usage: lasif plot_windows [-h] [--ipdb] [--read_only_caches] [--combine]
                              [--distance_bins DISTANCE_BINS]
                              iteration_name event_name

Plot the selected windows.

Positional Arguments
iteration_name name of the iteration
event_name name of the event
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--combine Create a combined plot for all windows of that event.
--distance_bins The number of bins on the distance axis for the combined plot.

lasif plot_stf

usage: lasif plot_stf [-h] [--ipdb] [--read_only_caches] iteration_name

Plot the source time function for one iteration.

Positional Arguments
iteration_name name of the iteration
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_kernel

usage: lasif plot_kernel [-h] [--ipdb] [--read_only_caches]
                             folder depth component filename

Directly plot a kernel to a file.

Useful for scripting LASIF. As they are not often in the LASIF project this is one of the view commands that will work on data outside of LASIF.

Positional Arguments
folder The folder containing the gradients.
depth The depth at which to plot.
component The component to plot.
filename Output filename. Use ‘-‘ to not write to a file but directly show the kernel.
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif plot_domain

usage: lasif plot_domain [-h] [--ipdb] [--read_only_caches]
                             [--no_simulation_domain]

Plot the project’s domain on a map.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--no_simulation_domain Don’t plot the simulation domain

Project Management Functions

Project Management

Functions dealing with LASIF projects as a whole.

lasif info

usage: lasif info [-h] [--ipdb] [--read_only_caches]

Print a summary of the project.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif list_kernels

usage: lasif list_kernels [-h] [--ipdb] [--read_only_caches]

Print a list of all kernels in this project.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif validate_data

usage: lasif validate_data [-h] [--ipdb] [--read_only_caches]
                               [--station_file_availability] [--raypaths]
                               [--waveforms] [--full]

Validate the data currently in the project.

This commands walks through all available data and checks it for validity. It furthermore does some sanity checks to detect common problems. These should be fixed.

By default is only checks some things. A full check is recommended but potentially takes a very long time.

Things the command does:

Event files:
  • Validate against QuakeML 1.2 scheme.
  • Make sure they contain at least one origin, magnitude and focal mechanism object.
  • Check for duplicate ids amongst all QuakeML files.
  • Some simply sanity checks so that the event depth is reasonable and the moment tensor values as well. This is rather fragile and mainly intended to detect values specified in wrong units.
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only
--station_file_availability asserts that all waveform files have corresponding station files. Very slow.
--raypaths assert that all raypaths are within the set boundaries. Very slow.
--waveforms asserts that waveforms for one event have only a single location and channel type. Fast.
--full run all validations.

lasif init_project

usage: lasif init_project [-h] [--ipdb] folder_path

Create a new project.

Positional Arguments
folder_path where to create the project
Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif list_models

usage: lasif list_models [-h] [--ipdb] [--read_only_caches]

Print a list of all models in the project.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif remove_empty_coordinate_entries

usage: lasif remove_empty_coordinate_entries [-h] [--ipdb]
                                                 [--read_only_caches]

Remove all empty coordinate entries in the inventory cache.

This is useful if you want to try to download coordinates again.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--read_only_caches sets all caches to read-only

lasif build_all_caches

usage: lasif build_all_caches [-h] [--ipdb] [--quick]

Build all caches to speed up subsequent operations.

This is optional and might take a while. Otherwise the caches are built on demand which works fine but might impede on some workflows.

Optional Arguments
-h, --help show this help message and exit
--ipdb If true, a debugger will be launched upon encountering an exception. Requires ipdb.
--quick Only check caches for folders that do not have a cache.