
MOLE: an open near real-time database-centric Earthworm subsystem.

  Matteo Quintiliani and Stefano Pintore
  Istituto Nazionale di Geofisica e Vulcanologia - Italy
  Mail bug reports and suggestions to <matteo.quintiliani@ingv.it> 


CONTENTS
  INTRODUCTION
  MOLE COMPONENTS AND SUPPORTED PLATFORMS
  MOLEDB: INSTALLATION AND CONFIGURATION
  EW2MOLEDB: INSTALLATION AND CONFIGURATION
  MOLEFACE: INSTALLATION AND CONFIGURATION
  HISTORY
  ACKNOWLEDGEMENT
  REFERENCES
  LICENSE


- INTRODUCTION

  Mole poster presented in Erice, May 2012 is available from
  http://hdl.handle.net/2122/8002

  Earthworm (Johnson et al. 1995) is an automatic processing system for
  earthquake localization. The initial objective of the project, started in 1993,
  was to provide rapid notification of seismic events. The original requirements
  were for a system able to manage hundreds of channels in near real-time with
  robustness and speed but not necessarily to have a persistent memory of the
  past events. Subsequently, an interactive subsystem was provided beside the
  automatic, it was made up of several modules for loading information in an
  Oracle® database and then retrieving it for pos-processing and alarm
  notifications. However, the last tested version of the Interactive Earthworm
  dates back to May 2003, after which, for various technical and operational
  reasons, it was discontinued.

  After several years of successful tests using Earthworm for seismic event
  detection in Italy (Mazza et al. 2008), INGV National Earthquake Center decided
  to substitute the pre-existing localization program with the Earthworm system,
  interfacing it with the current event revision procedures. The main issue was
  that the common output parameters produced by Earthworm, like phase picks,
  event locations, magnitudes, data triggers, and error messages were reported
  only by e-mail or recorded on local disk files: one has to deal with scattered
  files in diverse formats, whenever analyzing or debugging an Earthworm system.

  We decided to use a Database Management System (DBMS), a more advanced and
  homogeneous method to store the information, which allows making queries and
  developing new procedures for post-processing and seismic information
  dissemination. There already existed, and still exist, several examples of
  dedicated database-centric projects interfacing to Earthworm's core (Friberg et
  al. 2010a), among which the most widespread are HYDRA (Buland et al. 2009) and
  AQMS (ANSS 2010; Bhadha et al. 2010, Friberg et al. 2010b) which have been
  developed for different purposes but they both rely on the Oracle® DBMS.
  Adopting a commercial DBMS like Oracle® is technically unobjectionable but
  this choice could be too onerous for most of the Earthworm users, whose need
  could also be met with a solution based on open-source and free software
  currently available. The experience provided by the Winston software (Cervelli
  et al. 2004; Cervelli 2005) had already demonstrated that MySQL® DBMS could
  sustain the heavy load of storing in near real-time the waveforms coming from
  the Earthworm system. This fact encouraged us to rely on MySQL® to develop a
  new system capable of collecting all possible kinds of Earthworm messages.

  We have designed and developed Mole, an open-source and cross-platform
  Earthworm subsystem made up of a MySQL database schema, an Earthworm module,
  and a web interface. Although it sprang from INGV requirements, Mole is as
  general-purpose as possible in order to provide a high-level communication
  layer to Earthworm. In this sense, Mole intends to be a starting point for the
  Earthworm community to fire up a development effort for a new "Open Interactive
  Earthworm".


- MOLE COMPONENTS AND SUPPORTED PLATFORMS

  At present, Mole consists of:

    - moledb: a MySQL database which hosts Earthworm messages information. It
	must be created running the installation script containing all MySQL
	definitions.
    - ew2moledb: an Earthworm module which feeds moledb with information read
	from the Earthworm rings. It has to be compiled for the same architecture where
	Earthworm is running (Windows, Linux, Solaris, etc.).
    - moleface: a PHP web interface for browsing the information stored in
	moledb.

  Mole has been designed and developed taking in account the cross-platform
  compilation aspects. It can run on Windows and Unix-like operating systems
  such as Linux, Mac OS X and Solaris.


- MOLEDB: INSTALLATION AND CONFIGURATION

  * Install Mole MySql database
	Dependencies:
		A MySql server
	- cd moledb
	- Default, the script "moledb_master_script.sh" will create on localhost
		a database called "mole" and a user "moleuser" with password "molepass"
		To change these values edit "moledb_master_script.sh".
	- Run  ./moledb_master_script.sh <mysql-root-password>
		Answer "yes", "no", "no", "no"

	=============================================================
	* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
	* * * Master script for initializing a mole-database  * * * 
	* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 

	* Do you want to initialize a mole-database with name 'mole' ?
	  WARNING: All existing data will be removed.          [y/n] : 

	Database 'mole' -- Creating database with name 'mole'...
	Database 'mole' -- Creating user 'moleuser'...
	Database 'mole' -- Creating tables...
	Database 'mole' -- Creating region table...
	Database 'mole' -- Creating functions...
	Database 'mole' -- Creating stored procedures...
	Database 'mole' -- Creating views...
	Database 'mole' -- Creating triggers...

	* Do you want to create table 'ew_params_pick'?
	  WARNING: you should have privileges for executing SELECT
        	   on mysql database 'information_schema'.   [y/n] 
	Skipped!

	* INGV optional. Create other tables, view, functions, stored procedures, triggers? [y/n] 
	Skipped!

	* Do you want to populate the mole-database 'mole' for testing it? [y/n] 
	Skipped!
	=================================================================


- EW2MOLEDB: INSTALLATION AND CONFIGURATION

  Earthworm requires compiling 32-bit binaries even on 64-bit architectures.

  * Compiling ew2moledb:
      - Dependencies:
	  1) Earthworm environment configuration, for sure.
	  2) 32-bit Connector/C (libmysql), a MySQL client library for C development.
	     Download the 32-bit binary library for your platform
	     ( http://www.mysql.com/downloads/connector/c/ ) or compile the sources.
	     Only the sources of  "MySQL Connector/C (libmysql)" have been added it
	     within the ew repository, under earthworm/src/archiving/mole/mysql-connector-c-6.0.2
	     If you decide to compile libmysql from source on your Unix/Solaris computer, you need 'cmake'.
	     For Windows users, cmake is not strictly needed.
	     Get 'cmake' for your platform from http://www.cmake.org/cmake/resources/software.html

      - Automatic compilation procedure:

         From the directory earthworm/src/archiving/mole, you can run the usual commands:

	   Windows
	     # nmake /f makefile.nt

	   Unix systems
	     # make -f makefile.ux

	   Solaris
	     # make -f makefile.sol

	    On Unix/Solaris system you could have to set in your environment the
	    variable LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH), i.e.:

	        export LD_LIBRARY_PATH=$EW_HOME/$EW_VERSION/src/archiving/mole/mysql-connector-c-build/lib
	        setenv LD_LIBRARY_PATH $EW_HOME/$EW_VERSION/src/archiving/mole/mysql-connector-c-build/lib

  * Configure ew2moledb:

	- Use one of the following files:
		ew2moledb_hyporing.d
		ew2moledb_pickring.d
		ew2moledb_wavering.d
	- Copy them and .desc file to directory $EW_PARAMS
	- Edit the files 
	- Set properly the following variables:
		MyModuleId
		InRing
		DBHostname
		DBName
		DBUsername
		DBPassword
		GetMsgLogo ....	
		GetMsgLogo ....

  * Some UNNECESSARY notes about ew2moledb compilation:

        The automatic procedure approximately executes, for example on a unix machine:
                 # cd mysql-connector-c-build
                 # cd mysql-connector-c-6.0.2
                 # Within ./CMakeLists.txt add the option "-m32" to variables CMAKE_C**_FLAGS
                 # cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=../mysql-connector-c-build
                 # make 
                 # make install 
                 # cd ../ew2moledb
                 # make -f makefile.ux

        If the compilation is not static, then set properly the variable LD_LIBRARY_PATH, i.e.
                 # export LD_LIBRARY_PATH=/somewhere/mysql-connector-c-build/lib

        If you have already installed somewhere the mysql library as 32-bit, then you
        could compile ew2moledb following these steps:
	   - cd ew2moledb
	   - Edit the makefile.XXX for your architecture and set properly
		MYSQL_CONFIG_PROG_PATH
		with the path of program mysql_config
	   - Run "make -f makefile.XXX dynamic" and good luck ;-)


- MOLEFACE: INSTALLATION AND CONFIGURATION

    Moleface is based on the free open-source PHP framework Xataface 
    Download from http://xataface.com/
    Moleface has been successfully tested with Xataface 1.3.2

    Installation requirements:
        - Apache with PHP and MySQL support.


- HISTORY
    Read file HISTORY for release notes.


- ACKNOWLEDGEMENT

  * Salvatore Mazza - I.N.G.V.
  * Andrea Bono - I.N.G.V.
  * Valentino Lauciani - I.N.G.V.
  * Alfonso Mandiello - I.N.G.V.
  * Carlo Marcocci - I.N.G.V.
  * Franco Mele - I.N.G.V.
  * Laura Scognamiglio - I.N.G.V.
  * Paul Friberg - ISTI (Instrumental Software Technologies, Inc.)
  * Stefan Lisowski - ISTI


- REFERENCES

  ANSS (2010). AQMS: Advanced National Seismic System Quake Management
    System. http://vault.gps.caltech.edu/trac/cisn

  Bhadha, R., Chen, S., Crummey, J., Hauksson, E., Solanki, K., Thomas, V.
    I., Watkins, M., Yip, R., Yu, E., Given, D., Peats, R., and S. Schwarz (2010).
    Caltech/USGS Southern California Seismic Network: Recent Developments. American
    Geophysical Union, Fall Meeting 2010, abstract #S13C-2018.

  Buland, R. P., Guy, M., Kragness, D.; Patton, J., Erickson, B., Morrison,
    M., Bryon, C., Ketchum, D., and H. Benz (2009). Comprehensive Seismic
    Monitoring for Emergency Response and Hazards Assessment: Recent Developments
    at the USGS National Earthquake Information Center. American Geophysical Union,
    Fall Meeting 2009, abstract #S11B-1696.

  Cervelli, D. P., Cervelli, P. F., and T. L. Murray (2004). New Software for
    Long-Term Storage and Analysis of Seismic Wave Data. American Geophysical
    Union, Fall Meeting 2004, abstract #SF13A-0705.

  Cervelli, D. P. (2005). Winston Manual.
    http://www.avo.alaska.edu/Software/winston/W_Manual_TOC.html

  Friberg, P., CISN developers (2010b). A Reorganization of Earthquake
    Post-processing Systems at Regional Seismic Networks in the United States using
    AQMS. European Seismological Commission abstract, September 6-10, 2010,
    S21/Tu/O13.

  Friberg, P., Lisowski, S., Dricker, I., and S. Hellman (2010a). Earthworm
    in the 21st century. European Geosciences Union General Assembly 2010, held 2-7
    May, 2010 in Vienna, Austria, p.12654.

  Hannah, S. (2009). Xataface-A Better Way to Build a Front-end for Your
    MySQL Database. http://www.xataface.com/ .

  Johnson, C.E., A. Bittenbinder, B. Bogaert, L. Dietz, and W. Kohler (1995).
    Earthworm: a flexible approach to seismic network processing, IRIS Newsletter,
    14, 1-4.

  Mazza, S., Mele, F., Olivieri, M.,Pintore, S., Quintiliani, M.,
    Scognamiglio, L., and G. Selvaggi (2008). A new System for Earthquake Detection
    and Source Parameters Determination in Italy. European Seismological Commission
    ESC 2008, 31st General Assembly.

  Quintiliani, M., and S. Pintore (2012). Mole: an open near real-time
    database-centric Earthworm subsystem. Submitted to the Seismological
    Research Letters, June 1, 2012.


- LICENSE

    Software is open-source and released under GNU Library General Public License.

    This program is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.

    Read file COPYING for details.

