UCVM 13.9.0 Developer Guide - Revision history

Davidgil: /* Technical Implementation Details */

2013-09-13T18:35:33Z

Technical Implementation Details

Davidgil at 18:34, 13 September 2013

2013-09-13T18:34:28Z

Davidgil: /* General API Concepts */

2013-09-13T18:33:03Z

General API Concepts

Show changes

Davidgil: /* Overview */

2013-09-12T23:41:37Z

Overview

Davidgil: /* Register a New Velocity Model */

2013-09-12T23:40:47Z

Davidgil: /* Query a Velocity Model in Your Code */

2013-09-12T23:38:10Z

Query a Velocity Model in Your Code

Show changes

Davidgil at 23:36, 12 September 2013

2013-09-12T23:36:38Z

Davidgil: Created page with '== Overview == '''This guide is intended for users looking to modify the UCVM source code, register new models with UCVM, or integrate UCVM into their own projects. Most common …'

2013-09-12T23:33:35Z

Created page with '== Overview == '''This guide is intended for users looking to modify the UCVM source code, register new models with UCVM, or integrate UCVM into their own projects. Most common …'

New page

== Overview ==

'''This guide is intended for users looking to modify the UCVM source code, register new models with UCVM, or integrate UCVM into their own projects. Most common functionality, including mesh generation and getting material properties from models, is described in the [https://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide main user guide].'''

← Older revision		Revision as of 18:35, 13 September 2013
Line 404:		Line 404:

	== Technical Implementation Details ==		== Technical Implementation Details ==
		+
		+	=== SCEC CVM Etree Convention ===
		+
		+	==== Etree Model Format ====
		+	* Variable resolution based off of Vs, max supported frequency, and points per wavelength. The resolution at any particular region will be dependent upon the local Vs value (relation shown below). However, a minimum Vs at Etree creation will clamp the resolution to a maximum value regardless of how low the local Vs is found to be.
		+	<pre>
		+	rez = vs / (ppwl * freq)
		+
		+	where:
		+	vs: Vs at point of interest (m/s)
		+	ppwl: points per wavelength
		+	freq: max supported frequency (Hz)
		+	</pre>
		+	* Model data is referenced relative to free surface. Free surface is defined at air/ground, water/ground interface. UCVM topography and bathymetry can be used to determine if a point is in the air/water and default properties returned for those domains.
		+	* Stored properties are Vp, Vs, and density.
		+
		+
		+	==== Etree Metadata Description ====
		+
		+	The Etree metadata tag describes the payload of the octants, the extents of the coverage region, and the map projection. It will have the following format, with fields delimited by vertical bars:
		+
		+	<pre>
		+	metatype_version\|title\|author\|date\|vs_min\|max_freq\|ppwl\|format\|proj.4_string\|geo_origin\|rot_angle\|xyz_dims\|xyz_ticks
		+
		+	where:
		+	metatype_version: "SCEC_CVM_V1" string of max length 64 chars
		+	title: free-format title string of max length 64 chars
		+	author: free-format author string of max length 64 chars
		+	date: YY/MM/DD date string
		+	vs_min: vs minimum used to determine max resolution
		+	max_freq: maximum supported frequency in Hz
		+	ppwl: Points per wavelength
		+	format: data format specification of octants. Uses string format: "name,data_type,size,units". eg: "vp,float,4,m/s;vs,float,4,m/s;rho,float,4,kg/m^3"
		+	proj.4_string: Proj.4 projection string, eg: "+proj=aeqd +lat_0=36.0 +lon_0=-120.0 +x_0=0.0 +y_0=0.0"
		+	geo_origin: Origin point of CVM region in geo coordinates, eg: "-129.25,41.0"
		+	rot_angle: Rotation angle of bounding box in degrees, eg "55.0"
		+	xyz_dims: Dimensions of bounding box in km, eg "1800,800,100"
		+	xyz_ticks: Number of ticks along each dimension
		+	</pre>
		+
		+
		+	=== SCEC Patch Model Format ===
		+
		+	A patch model consists of five files: a configuration text file, and four binary files with the surface data. All of these files are automatically generated by the patchmodel utility. The sections below describe the file formats.
		+
		+
		+	==== Configuration file ====
		+
		+	The patch model configuration file specifies the origin, dimensions, and map projection of the 3D region covered by the patch. An example follows:
		+
		+	<pre>
		+	# cvmh patch conf file
		+
		+	# Version
		+	version=cvmh_p1_2011/05/24
		+	# Projection
		+	proj=+proj=aeqd +lat_0=36.0 +lon_0=-120.0 +x_0=0.0 +y_0=0.0
		+	lon_0=-121.300000
		+	lat_0=35.600000
		+	rot=90.000000
		+	# Spacing
		+	spacing=250.000000
		+	# Dimensions
		+	x-size=550000.000000
		+	y-size=50000.000000
		+	z-size=112500.000000
		+	# Paths to surface files
		+	surf_0_0_path=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p1_surf_0_0.bin
		+	surf_1_0_path=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p1_surf_1_0.bin
		+	surf_0_1_path=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p1_surf_0_1.bin
		+	surf_1_1_path=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p1_surf_1_1.bin
		+	</pre>
		+
		+
		+	==== Surface Files ====
		+
		+	The surface file format is a 2D array of three floating point values: vp, vs, and density. The assignment of x versus y axis in each file is dependent on the orientation of the surface with respect to the box's origin point.
		+
		+
		+	=== SCEC Map Etree Convention ===
		+
		+	==== Etree Model Format ====
		+
		+	* 3D Etree with a single octant depth along Z-axis (effectively a 2D grid)
		+	* Fixed resolution based off of maximum desired grid spacing in grd2etree configuration.
		+	* Sampled with grid registration to allow smoothing of adjacent octants in UCVM.
		+	* Stored values at each grid point are: surface elevation (float), Vs30 (float).
		+
		+
		+	==== Etree Metadata Description ====
		+
		+	The Etree metadata tag describes the payload of the octants, the extents of the coverage region, and the map projection. It will have the following format, with fields delimited by vertical bars:
		+
		+	<pre>
		+	metatype_version\|title\|author\|date\|spacing\|format\|proj.4_string\|geo_origin\|rot_angle\|xy_dims\|xyz_ticks
		+
		+	where:
		+	metatype_version: "SCEC_MAP_V1" string of max length 64 chars
		+	title: free-format title string of max length 64 chars
		+	author: free-format author string of max length 64 chars
		+	date: YY/MM/DD date string
		+	spacing: grid spacing in meters
		+	format: data format specification of octants. Uses string format: "name,data_type,size,units". eg: "surf,float,4,m/s;vs30,float,4,m/s;"
		+	proj.4_string: Proj.4 projection string, eg: "+proj=aeqd +lat_0=36.0 +lon_0=-120.0 +x_0=0.0 +y_0=0.0"
		+	geo_origin: Origin point of CVM region in geo coordinates, eg: "-129.25,41.0"
		+	rot_angle: Rotation angle of bounding box in degrees, eg "55.0"
		+	xy_dims: Dimensions of bounding box in km, eg "1800,800"
		+	xyz_ticks: Number of ticks along each dimension
		+	</pre>

← Older revision		Revision as of 18:34, 13 September 2013
Line 401:		Line 401:

	</pre>		</pre>
		+
		+
		+	== Technical Implementation Details ==

← Older revision		Revision as of 23:41, 12 September 2013
Line 4:		Line 4:

	Released on September 8th, 2013, UCVM 13.9.0 represents the second major release of the Unified Community Velocity Model (UCVM) framework. While at its core, UCVM is a collection of software utilities that are designed to make interacting with velocity models easier, it also includes a powerful API for interacting with or registering new velocity models. UCVM's API makes it very easy to integrate into software projects.		Released on September 8th, 2013, UCVM 13.9.0 represents the second major release of the Unified Community Velocity Model (UCVM) framework. While at its core, UCVM is a collection of software utilities that are designed to make interacting with velocity models easier, it also includes a powerful API for interacting with or registering new velocity models. UCVM's API makes it very easy to integrate into software projects.
		+
		+	This guide will walk you through some of the common API functions and steps required to get UCVM to work either with your code or to have it work within your code.

	== Register a New Velocity Model ==		== Register a New Velocity Model ==

← Older revision		Revision as of 23:40, 12 September 2013
Line 6:		Line 6:

	== Register a New Velocity Model ==		== Register a New Velocity Model ==
		+
		+	UCVM can be extended to query any velocity model provided that certain conditions are met. Every new velocity model must have at least:
		+
		+	Unless the model is packaged in e-tree format, implementing it will require code modifications to the core UCVM library located in ./src/ucvm and recompilation. The general steps are:
		+
		+	* Define new model label UCVM_MODEL_MODELNAME in ucvm_dtypes.h
		+	* Create ucvm_model_modelname.h/.c containing the glue code that links the UCVM query interface to the native model interface
		+	* Modify ./src/ucvm/ucvm.c:
		+	** Add ucvm_model_modelname.h include at top
		+	** Add model lookup to ucvm_add_model() function
		+	** Add model to ucvm_get_resources() function
		+	* Modify ./src/ucvm/Makefile.am:
		+	** Add ucvm_model_modelname.o to list of libucvm.a dependencies
		+	* Modify ./configure.ac:
		+	** Define "enable-modelname", "with-modelname-lib-path", and "with-modelname-incl-path" configure options
		+	** Add library and header checks for your new model
		+	* Modify installer to customize path to your new model in ucvm.conf:
		+	** Add your new model to ./conf/Makefile.am
		+	** Add config entry for your new model to ./conf/ucvm_template.conf
		+	* Regenerate the Makefiles with ./scripts/autoconf/reconf.sh
		+	* Reconfigure and recompile UCVM, making sure to pass your new model flags to the configure utility

	== Query a Velocity Model in Your Code ==		== Query a Velocity Model in Your Code ==

← Older revision		Revision as of 23:36, 12 September 2013
Line 2:		Line 2:

	'''This guide is intended for users looking to modify the UCVM source code, register new models with UCVM, or integrate UCVM into their own projects. Most common functionality, including mesh generation and getting material properties from models, is described in the [https://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide main user guide].'''		'''This guide is intended for users looking to modify the UCVM source code, register new models with UCVM, or integrate UCVM into their own projects. Most common functionality, including mesh generation and getting material properties from models, is described in the [https://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide main user guide].'''
		+
		+	Released on September 8th, 2013, UCVM 13.9.0 represents the second major release of the Unified Community Velocity Model (UCVM) framework. While at its core, UCVM is a collection of software utilities that are designed to make interacting with velocity models easier, it also includes a powerful API for interacting with or registering new velocity models. UCVM's API makes it very easy to integrate into software projects.
		+
		+	== Register a New Velocity Model ==
		+
		+	== Query a Velocity Model in Your Code ==
		+
		+	== General API Concepts ==