UCVM Command Reference

From SCECpedia
Revision as of 23:04, 3 December 2016 by Maechlin (talk | contribs)
Jump to navigationJump to search

UCVM Command Reference (v15.10.0)

UCVM Software Collection

The UCVM software is a software framework that builds on top of several existing scientific software packages, including CVM-H, CVM-S4, and the USGS Bay Area Model. The UCVM installation process involves first compiling the individual CVM programs, and then compiling and installed the UCVM framework.

The UCVM installation process involves two code directory trees, the src tree, and the bin tree. UCVM source codes and models are collected in the src directory tree. When UCVM is built, it is installed into a separate directory location, called the bin directory tree. Once UCVM is correctly built and installed, user configure their computing environment to point to the bin directory. All supported UCVM commands are contained in the UCVM bin tree.

Command Reference Conventions

We base our instructions and documentation assuming a standard open source software environment.

Default installation operating system is a 2015 or later Linux distribution with Python 2.7, multiple packages, gnu c and fortran compilers.

Default user shell is a bash shell and our documentation.

We will call the bin directory tree $UCVM_HOME_DIR in the command descriptions below:

UCVM commands are located in the bin tree, in several directories including $UCVM_HOME_DIR/bin, /tests, /utilities, /scripts

/bin

  1. basin_query
  2. ecoalesce
  3. ecompact
  4. grd2etree
  5. grd_query
  6. mesh-check
  7. mesh-op
  8. mesh-strip-ijk
  9. patchmodel
  10. run_grd.sh
  11. run_ucvm.sh
  12. ssh_generate
  13. ssh_merge
  14. ucvm2etree
  15. ucvm2mesh
  16. ucvm_query
  17. vs30_query

basin_query

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    basin_query

SYNOPSIS

    basin_query [-h] [-f config-file] [-m model] [-v vs-threshold]

[-p usermap] [-z zmin,zmax] [-d max-depth] [-i interval] < file.in

DESCRIPTION

    The command basin_query allows you to retrieve the depth at which
    vs-threshold is first crossed. By default, vs-threshold is set to be
    1000m/s, but that can easily be changed.
    Common Paramters
    -f       Location of the UCVM configuration file. Typically, this is

../conf/ucvm.conf.

    -m       Model to query. Usually model is either cvms, cvmh, cvmsi, or

cencal.

    -v       Vs threshold to use. By default this is 1000m/s, but other com-

mon values include 2500m/s and 3000m/s.

    Less Used Parameters
    -p       Custom vs30 and elevation map location.
    -z       Custom depth range for GTL/crust interpolation.
    -d       Maximum depth, in meters, to search. Default is 15000m.
    -i       Interval, in meters, go go by when searching for the depth.

Default is 20m. So basin_query will get the Vs value at 0m, 20m, 40m, and so on.

EXAMPLE

    basin_query -f ../conf/ucvm.conf -m cvms -v 2500

Input: -118 34 Ctrl-D

Output: -118.0000 34.0000 4780.000 4780.000

SEE ALSO

    ucvm_query(1)

Linux December 3, 2016 Linux

ecoalesce

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    ecoalesce

SYNOPSIS

    ecoalesce [-h] input output

DESCRIPTION

    The command ecoalesce helps compact an e-tree file that conforms either
    to CMU or SCEC standards. It does this by replacing eight adjacent
    octants with identical material properties at level N with a single
    octant containing the same material properties at level N-1. Usually,
    this command is run with ecompact as well.
    Common Paramters
    -h       Shows the help message.
    input    E-tree input file. Typically, this was just extracted with the

ucvm2etree utilities.

    output   Compacted e-tree output.

EXAMPLE

    ecoalesce chino_hills.etree compacted_chino_hills.etree

SEE ALSO

    ecompact(1), ucvm2etree(1), ucvm2etree-extract-MPI(1),
    ucvm2etree-merge-MPI(1), ucvm2etree-sort-MPI(1)

Linux December 3, 2016 Linux

ecompact

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    ecompact

SYNOPSIS

    ecompact [-h] input output

DESCRIPTION

    The command ecompact helps compact an e-tree file that conforms either to
    CMU or SCEC standards.  It does this by removing empty space in the Etree
    data structure. Usually, this command is run with ecoalesce as well.
    Common Paramters
    -h       Shows the help message.
    input    E-tree input file. Typically, this was just extracted with the

ucvm2etree utilities.

    output   Compacted e-tree output.

EXAMPLE

    ecompact chino_hills.etree compacted_chino_hills.etree

SEE ALSO

    ecoalesce(1), ucvm2etree(1), ucvm2etree-extract-MPI(1),
    ucvm2etree-merge-MPI(1), ucvm2etree-sort-MPI(1)

Linux December 3, 2016 Linux

grd_query

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    grd_query

SYNOPSIS

    grd_query [-h] [-e] [-v] -d datadir [-b bkgdir] < file.in

DESCRIPTION

    The command grd_query queries data from a set of ArcGIS grid files in
    GridFloat format.
    -h       Shows the help message.
    -e       Employ GRD bathymetry heuristic.
    -v       Employ GRD vs30 heuristic.
    -d       Main ArcGIS Gridfloat data directory. Default is ./ned.
    -b       Background/Bathymetry data directory. Default is ./bath.

EXAMPLE

    Input format is:

lon lat

    Output format is:

lon lat val valid

SEE ALSO

    grd2etree(1)

Linux December 3, 2016 Linux

grd2etree

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    grd2etree

SYNOPSIS

    grd2etree [-h] -f config

DESCRIPTION

    The command grd2etree extracts a SCEC-formatted Etree map from a set of
    DEM and Vs30 grid files in ArcGIS Gridfloat format.
    Common Paramters
    -h       Shows the help message.
    -f       Specifies the location of the configuration file to use.

EXAMPLE

    grd2etree -f ./grd2float_sample.conf
    Where grd2float_sample.conf looks like:
    # grd2etree UCM Map config file
    # Domain corners coordinates (degrees): proj=+proj=aeqd +lat_0=36.0
    +lon_0=-120.0 +x_0=0.0 +y_0=0.0 lon_0=-129.75 lat_0=40.75 rot=55.0
    # Domain dimensions (meters): x-size=1800000.0 y-size=900000.0
    # Spacing spacing=250.0
    # Etree parameters and info title=UCVM_Elev_Vs30_Map_Wills_Wald
    author=P_Small date=05/2011 outputfile=../../model/ucvm/ucvm.e
    # Grid data directories elev_hr_dir=/home/scec-00/USER/opt/ned
    elev_lr_dir=/home/scec-00/USER/opt/bath
    vs30_hr_dir=/home/scec-00/USER/opt/vs30/wills_gridfloat
    vs30_lr_dir=/home/scec-00/USER/opt/vs30/wald_gridfloat

SEE ALSO

    grd_query(1)

Linux December 3, 2016 Linux

mesh-check

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    mesh-check

SYNOPSIS

    mesh-check input format

DESCRIPTION

    The command mesh-check does a basic quality assurance check of a mesh
    file. It checks to make sure that each record in the file is of the cor-
    rect size. Furthermore, it checks to make sure that each value is not
    NaN, infinity, or negative.
    input    The input mesh to check.
    format   The mesh format. Can be either IJK-12, IJK-20, or IJK-32

EXAMPLE

    mesh-check new_mesh.mesh IJK-12

SEE ALSO

    mesh-op(1), mesh-strip-ijk(1)

Linux December 3, 2016 Linux

mesh-op

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    mesh-op

SYNOPSIS

    mesh-op op inmesh1 inmesh2 format outmesh

DESCRIPTION

    The command mesh-op subtracts inmesh2 from inmesh1 and outputs the dif-
    ference to outmesh.
    op       The operation. Currently the only supported operation is "diff".
    inmesh1  The first mesh to read.
    inmesh2  The second mesh to read.
    format   Supported formats include IJK-12, IJK-20, and IJK-32.
    outmesh  The mesh that represents inmesh1 - inmesh2.

EXAMPLE

    mesh-op diff ./inmesh1 ./inmesh2 IJK-12 ./outmesh

SEE ALSO

    mesh-check(1), mesh-strip-ijk(1)

Linux December 3, 2016 Linux

mesh-strip-ijk

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    mesh-strip-ijk

SYNOPSIS

    mesh-strip-ijk inmesh format outmesh

DESCRIPTION

    The command mesh-strip-ijk converts an IJK-20 or IJK-32 mesh, inmesh, to
    an IJK-12 formatted mesh, outmesh.
    inmesh   The input mesh in IJK-20 or IJK-32 format.
    format   The format of the input mesh (IJK-20 or IJK-32).
    outmesh  The resulting IJK-12 mesh.

EXAMPLE

    mesh-strip-ijk ijk20_mesh IJK-20 output_mesh

SEE ALSO

    mesh-check(1), mesh-op(1)

Linux December 3, 2016 Linux

ucvm2etree-extract-MPI.txt

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    ucvm2etree-extract-MPI

SYNOPSIS

    ucvm2etree-extract-MPI [-h] -f config

DESCRIPTION

    Notice: This command is intended to be run as a MPI job (e.g. mpirun
    ./ucvm-extract-MPI).  Please do not attempt to run it as a regular
    process.
    The command ucvm2etree-extract-MPI extracts components of an e-tree from
    the specifications in a given configuration file, config.
    Specifically, it divides the etree region into C columns for extraction.
    This is an embarrassingly parallel operation. A dispatcher (rank 0) farms
    out each column to a worker in a pool of N cores for extraction. Each
    worker queries UCVM for the points in its column and writes a flat-file
    formatted etree. After program execution, there are N sub-etree files,
    each locally unsorted. The extractor must be run on 2^Y + 1 cores where
    Y>0 and (2^Y) < C. The output flat file format is a list of octants(24
    byte addr, 16 byte key, 12 byte payload) in arbitrary Z-order.
    Since the number of points in a column depends on the minimum Vs values
    within that column, some columns will have high octant counts and others
    will have very low octant counts. Having sub-etrees that vary greatly in
    size is not optimal for the sorting operations that follow, so
    ucvm2etree-extract-MPI implements a simple octant balancing mechanism.
    When a worker has extracted more than X octants (the default 16M
    octants), it reports to the dispatcher that it cannot extract any more
    columns and terminates.  This strategy approximately balances the sub-
    etrees so that they may be loaded into memory by ucvm2etree-sort-MPI. In
    the case of very large extractions where the dispatcher reports that all
    workers have reported they are full yet columns remain to be extracted,
    increase the job size by a factor of 2 until there is room for all the
    columns.
    You would typically run this command, followed by ucvm2etree-sort-MPI and
    ucvm2etree-merge-MPI.
    -h       Displays the help message.
    -f       Uses configuration file, config.

EXAMPLE

    mpirun -np 768 ucvm2etree-extract-MPI -f ./ucvm2etree_example.conf
    Where ucvm2etree_example.conf is:
    # Domain corners coordinates (clockwise, degrees):
    proj=geo-bilinear
    lon_0=-119.288842
    lat_0=34.120549
    lon_1=-118.354016
    lat_1=35.061096
    lon_2=-116.846030
    lat_2=34.025873
    lon_3=-117.780976
    lat_3=33.096503
    # Domain dimensions (meters):
    x-size=180000.0000
    y-size=135000.0000
    z-size=61875.0000
    # Blocks partition parameters:
    nx=32
    ny=24
    # Max freq, points per wavelength, Vs min
    max_freq=0.5
    ppwl=4.0
    vs_min=200.0
    # Max allowed size of octants in meters
    max_octsize=10000.0
    # Etree parameters and info
    title=ChinoHills_0.5Hz_200ms
    author=D_Gill
    date=05/2011
    outputfile=./cmu_cvmh_chino_0.5hz_200ms.e
    format=etree
    # UCVM parameters
    ucvmstr=cvms
    ucvm_interp_zrange=0.0,350.0
    ucvmconf=../../conf/kraken/ucvm.conf
    # Scratch
    scratch=/lustre/scratch/scecdave/scratch
    #
    # Buffering parameters used by MPI version only
    #
    # Etree buffer size in MB
    buf_etree_cache=128
    # Max octants to buffer for flat file during extraction
    buf_extract_mem_max_oct=4194304
    # Max octants to save in flat file before reporting full during extrac-
    tion
    buf_extract_ffile_max_oct=16000000
    # Max octants to read from input flat file during sorting
    buf_sort_ffile_max_oct=20000000
    # Minimum number of octants between reports during merging
    buf_merge_report_min_oct=10000000
    # MPI send/recv octant buffer size during merging
    buf_merge_sendrecv_buf_oct=4096
    # Etree read/write octant buffer size during merging
    buf_merge_io_buf_oct=4194304

SEE ALSO

    ucvm2etree-sort-MPI(1), ucvm2etree-merge-MPI(1), ucvm2etree(1)

Linux December 3, 2016 Linux

ucvm_query

UCVM(1) BSD General Commands Manual UCVM(1)

NAME

    ucvm_query

SYNOPSIS

    ucvm_query [-h] [-f config] [-m model] [-c coordtype] [-p map] [-v]

[-z zmin,zmax]

DESCRIPTION

    The command ucvm_query queries an installed velocity model to retreive
    its material properties at a particular latitude and longitude.
    Any set of crustal and GTL velocity models may be selected and queried in
    order of preference. Points may be queried by (lon,lat,dep) or
    (lon,lat,elev) and the coordinate conversions for a particular model are
    handled transparently.
    Common Paramters
    -h       Displays the help message.
    -f       Location of the configuration file, config, that tells the pro-

gram which velocity models are installed.

    -m       A comma-separated list of models to query.
    Less Used Parameters
    -c       Z-coordinate mode. Geo-depth (default) is "gd", but queries can

also be done by elevation as specified by "ge".

    -p       User-defined map of vs30 and elevation data.
    -v       Display model version information only.
    -z       Specifies depth range for gtl/crust interpolation.

EXAMPLE

    ucvm_query -f ../conf/ucvm.conf -m cvms
    Input format is:

lon lat Z

    Output format is:

lon lat Z surf vs30 crustal cr_vp cr_vs cr_rho gtl gtl_vp gtl_vs

    gtl_rho cmb_algo cmb_vp cmb_vs cmb_rho
    If running in interactive mode, please use Ctrl-D to end the input.

SEE ALSO

    basin_query(1)

Linux December 3, 2016 Linux

Related Entries