SeisComP3 release Jakarta-2017.334

Dec. 1, 2017

Categories:
release
SeisComP3

First some statistics for all changes and bugfixes:

We have removed 144549 and added 329135 lines of code. In total 1388 files were changed. 50% of those numbers are related to the generation of the Python wrappers with Swig. Another big chunk is related to the update of 3rd party libraries such as libbson 1.7.0 and Spread 4.4.0

Database upgrade

When installing a new SeisComP3 release upgrading the database may be required. With this new release we start to provide database schema migration scripts which allow incremental upgrades of the database schema version. The database version will be tested and the required actions will be shown when executing

seiscomp update-config

or when pressing the Update Configuration button in scconfig. An upgrade from version 2017.124 will give:

* starting kernel modules
spread is already running
starting scmaster
* configure scmaster
  * check database write access ... OK
  * database schema version is 0.9
  * last migration version is 0.10
  * migration to the current version is required. apply the following
    scripts in exactly the given order:
    * /home/sysop/seiscomp3/share/db/migrations/mysql/0_9_to_0_10.sql
error: updating configuration for scmaster failed

The shown migration scripts can be used directly with the mysql command:

$ mysql -u sysop -p -D seiscomp3 -e 'source /home/sysop/seiscomp3/share/db/migrations/mysql/0_9_to_0_10.sql;'

Using the migration scripts provides a more user friendly way than copying the lines of mysql code from the changelog. In later versions we might add the option to automatically run the migrations.

scolv

system tray icon

System tray icon.

switch

Switch for enabling and disabling observations used for event location.

magnitude selection

Magnitudes can be selected and unselected.

The map in scolv received a new layer that renders event symbols for all events loaded into the event list. By default this layer is invisible. To show it, either activate it via the map context menu or add the following configuration:

map.layers.events.visible = true

Any symbol can be double clicked to activate the event. This is similar to activate an event from the event list.

The status codes of an event/origin have been extended. Now all status enumerations are mapped to a single character. The color is still being used to distinguish manual and automatic mode. The following mapping is applied:

preliminary P
confirmed C
reviewed V
final F
rejected X
reported R
- manual ? M : A

In order to test the GUI applications in a normal environment without being able to impact the SeisComP3 system, we added optional blacklist parameters for users or authors. These parameters prevent that data products can be sent to the messaging from a GUI that was started with a particular user or author parameter, e.g.:

blacklist.users = sysop1, sysop2
blacklist.authors = sysop1@host, sysop2@host

This does not implement a real permission model on the server but only adds checks at client side. That implies that this safety model relies on cooperation to e.g. prevent accidental commits from a demo system.

The event summary, often used in scolv may now automatically change its color and font size based on the comment of an event. The changes may be used to indicate the urgency level and trigger actions by an operator. Such comments may be manually added to events in scolv or automatically by other modules. We have added support for the event summary window to listen to such alert comments and to adapt the size and the color of the time ago label accordingly.

When starting scolv, a new small icon will appear in the system tray. When new events arrive, a notification will pop up for some seconds above this icon alerting active operators.

A new locator interface provides the option to enable or disable observations that may come along with pick objects. The primary observation is the actual pick time. However, detector modules or operators may additionally provide parameters such as the slowness or the backazimuth related to the detection. Such observations may be fed into locator tools and treated individually.

Manual magnitude calculations in scolv have received additional attention. All magnitude types selected for computation are now shown in the Magnitude tab of scolv including even those without station magnitudes. We have also added a button to manually remove magnitude types from further analysis. In this way the magnitude computations will become more transparent to the operator than before.

scmv

The mapview, scmv, has received the additional functionality to select events from its position on the map and to open the preferred origin in scolv. The new function can be accessed by clicking on the symbol of the event on the map. Then, just select one of the shown event IDs, view the parameters in the details window and click on the new button "Show Details". This opens the preferred origin of this event in scolv where it can be analysed.

This new function complements the already existing events table in scolv.

It furthermore received a legend for the color scale and the sizes of event symbols.

scmm

scmm is the graphical front end to view messages sent by SeiscComP3 modules. This GUI module is useful for debugging and understanding messages. We have added the documentation for this module.

scart

The waveform archiving tool scart has become even faster. Thanks to a contribution by the very active SeisComP3 community, retrieving a sorted miniSEED file from the SDS archive can now be more than 10 times faster.

scinv

When inventory files have conflicting parameters, scinv issues a warning. Now scinv also reports the files that contain the conflicts allowing users to debug the issue.

scbulletin

We have added the option --enhanced or -e to scbulletin. With this option almost all output will be given at the precision of meters and milliseconds. This option especially enhances the output event parameters from local earthquakes.

scevent

We have added the MODE comparison to the list of possible priority tokens in scevent. In this way fine-grained priority can be given to manual and automatic origins with thir specific STATUS.

scevtlog

The new module parameter gzip has been added in order to compress the XML files in gzip compatible format.

sh2proc

Seismic Handler is still in use by many scientists. With sh2proc we provide a new module for converting SeismicHandler event data to SC3ML.

scsohlog

scsohlog is a proven commandline tool that connects to the messaging system. It collects information sent from clients that can be used by user-customized scripts. We have brought this module alive by adding a short documentation.

scquery

scquery is another useful tool allowing users to generate and to use SQL commands querying SeisComP3 databases for event parameters. In this way SeisComP3 users can extract event parameters based time, location, magnitude and any other event related parameter. Also for this module we have added a short but descriptive documentation including a few examples.

Inventory import

The inventory import from SEED and StationXML has received a major update. Together with Arnaud Lemarchand from IPGP France we have improved the conversion tools with respect to response stage interpretation and comments. His deep knowledge of instrument configurations and his intensive tests took us to the current version. We have added an representation for StationXML response coefficients. Prior to that, coefficients were imported as fir responses with the result of losing the denominators. So we added an iir response type for which the conversion is fully supported. Furthermore to preserve SEED/StationXML station and channel comments, we added comments to all levels of the station tree: network, station, sensorLocation, stream. The latter requires the stream to become a PublicObject. Part of the database schema migration is generating publicIDs for all existing stream rows in the database. If an old (prior to version 0.10) SeisComP3 XML is being read into SeisComP3, publicIDs for each Stream object will be generated according to the configured publicID pattern. To make a long story short: comments are preserved when converting from and to StationXML/SEED. Additionally, fdsnws has been adopted to read comments from the database and to populate the result document.

C++ API changes

Many changes affect the GUI library. But there are some changes for common API usage. In particular it affects magnitude, locator and recordstream implementations.

MagnitudeProcessor

The method Seiscomp::Processing::MagnitudeProcessor::computeMagnitude received two additional parameters, hypocenter and receiver. The hypocenter holds a pointer to an origin for which the magnitude is computed. The receiver holds a pointer to the sensor location of the data that is processed. That allows for magnitude regionalization. The API change has been requested by Geoscience Australia and an example usage could be found in their Github repository.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
Status computeMagnitude(double amplitude, double period,
                        double delta, double depth,
#ifdef SC_API_VERSION >= SC_API_VERSION_CHECK(11,0,0)
                        const DataModel::Origin *hypocenter,
                        const DataModel::SensorLocation *receiver,
#endif
                        double &value) {
#ifdef SC_API_VERSION >= SC_API_VERSION_CHECK(11,0,0)
    // Starting from API 11 you can now access hypocenter and receiver. Note that
    // both pointers may be NULL.
#endif
}

LocatorInterface

The C++ interface to the event locators Seiscomp::Seismology::LocatorInterface received an important change to be able to select individual pick observations that shall be used by the locator. Until now, only a weight could be assigned which was interpreted as binary value, on or off. When a pick weight was on then all its observations were used: time, backazimuth and slowness. But there are cases where only the backazimuth and slowness should be used and not the time. So instead of a single weight we switched to three individual flags for each measure. The default is to use all three observations if available, but user code can now be more selective. The new scolv arrival table makes use of that change.

The affected methods are:

Origin *locate(PickList &);
Origin *locate(PickList &, double, double, double, const Time &);

The PickList now contains tuples of a pick and its flags rather than a pick and its weight. To write code that works for both API versions, a new define has been added:

#define SC3_LOCATOR_INTERFACE_VERSION 2

RecordStream

The RecordStream interface to load waveforms into SC3 application worked for quite a while now. But with more complex implementations in mind, it gets rather complicated to maintain speed and stability. The reason was that the interface itself does not read the records but provides methods to return a bytestream which will be used to deserialize a record. This works well for simple implementations such as Seedlink or Arclink or file but when it comes to more complex implementations such as redundant data retrieval or routers, this bytestream concept does not hold any longer in an easy way. So the RecordStream interface has been reworked and is now similar to the RecordInput (which is kind of obsolete now). The RecordStream has now full control over the bytestream and just returns complete records. The basic acquistion loop looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
using namespace Seiscomp;

// Open a record stream with URL notation
IO::RecordStreamPtr rs = IO::RecordStream::Open("slink://localhost");
if ( rs ) {
    rs->addStream("GE", "MORC", "", "BHZ");
    rs->addStream("GE", "MORC", "", "BHN");
    rs->addStream("GE", "MORC", "", "BHE");

    RecordPtr rec;
    while ( (rec = rs->next()) ) {
        // Do something with rec
    }

    // Close record stream
    rs.close();
}

That speeds up the implementation of the built-in balanced record stream (balanced://) as well as the gempa routing record stream (router://). To sum it up, remove the following methods from your own implementation:

1
2
3
4
std::istream &stream();
Record *createRecord(Array::DataType, Record::Hint);
void recordStored(Record *);
bool filterRecord(Record *);

and add the new method:

1
Record *next();

Python API Changes

The API mostly changed with respect to exception types. Rather than throwing wrapped SC3 exceptions, we either raise the Python ValueError exception which corresponds to the C++ Seiscomp::Core::ValueException and replaces the old Python seiscomp3.Core.ValueException or the Python RuntimeError which corresponds to all other C++ exceptions. See the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Old code
try:
    print station.latitude()
except seiscomp3.Core.ValueException e:
    print >> sys.stderr, "Station latitude is not set"

# New code
try:
    print station.latitude()
except ValueError e:
    print >> sys.stderr, "Station latitude is not set"

Furthermore the seiscomp3.Config.Exception was replaced with the Python Exception. See the code below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Old code
try:
    param = self.configGetString("param")
except seiscomp3.Config.Exception e:
    print >> sys.stderr, "param is not set"

# New code
try:
    param = self.configGetString("param")
except Exception e:
    print >> sys.stderr, "param is not set"