SCRUG-NA/2025
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[installation] Change to nightly

Browse Source
This commit is contained in:
Dirk Rössler
2025-10-30 12:04:59 +01:00
parent 2ff097f9d1
commit a31bc45cce
1441 changed files with 60368 additions and 56360 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
share/doc/seiscomp/html/_sources/base/CHANGELOG.md.txt
View File

@ -2,68 +2,187 @@
All notable changes to SeisComP are documented here.
## 6.9.0
## x.y.z
```SC_API_VERSION 16.4.0```
```SC_API_VERSION 17.0.0```
- fdsnxml2inv
- Fix samplerate conversion from double to fraction.
- scmv
- Fix crash if origin depth is not set.
- fdsnws
- Fix data availability sort for Python >= 3.13.
- Fix conditional station requests. Requests involving the
If-Modified-Since header failed since Twisted
version 24.7. The http.stringToDatetime() now requires a
byte string.
With this version we add support for Qt 6 of all GUI applications. Binary distributions
will build against the Qt version which is available by default in the respective
Linux distribution, either Qt 5 or Qt 6.
The database schema changes from version 0.13.2 to 0.14. This basically incorporates
the addition of a new object `Catalog` as part of the EventParameters datamodel and
changes indexes from object `QCLog`. Both objects are not yet used in SeisComP and
they are added as basis for new features. The database schema applies changes in its
datatypes: BLOBS will be converted to LONGTEXT (MySQL) or TEXT (PostgreSQL, SQLite3).
The database migration to schema version 0.14 can be a long lasting operation so
please schedule a downtime of your system accordingly.
Furthermore the foreign key constraints from a concrete type table like Origin to
the Object table is removed. This constraint was never required by SeisComP itself
as it takes care of correct removal of all derived table rows but it introduces a
performance penalty when deleting objects. Dropping the constraint might affect
custom database script which rely on it. Please be aware of that change.
- seiscomp
- Fix module count with `seiscomp status`
- documentation
- Consider new parameters `values` and `range` in description of
configuration and command-line parameters which will be highlighted in
documentation and exposed in scconfig.
- trunk
- Fix LOCSAT station correction file lookup if `SEISCOMP_LOCSAT_TABLE_DIR`
environment variable is being used.
- Decode tokens when parsing a URL.
- scevent
- Provide optional REST API to return the target event an origin would be
associated to.
## 6.8.4
- scevent
- Read `eventAssociation.minimumScore` from configuration.
## 6.8.3
- caps_plugin
- Exit if pipe to `seedlink` is broken.
- trunk
- Fix crash with empty filter parameter list and newer
C++ compiler versions.
- Do not call combined:// real-time recordstream with zero
requests.
## 6.8.2
- ITAPER(): Support time spans with double precision, update filter
documentation.
- Application CLI option `-q, --quiet` took an argument which was not
correct. It has been converted to a switch without argument.
- Add `minPeriod` and `maxPeriod` to amplitude type configuration. Both
are checked against the measured period to skip emitting amplitudes which
are outside the allowed period range.
- Support amplitude data conversion without `enableResponses = true`,
e.g. when computing amplitudes on acceleration data. This implicitly
includes support for amplitude updates for such data.
- Add locrouter plugin, see
https://github.com/SeisComP/common/blob/master/plugins/locator/router/descriptions/global_locrouter.rst.
- Speed up trace rendering for large number of records.
- Add support for reading GeoJSON and BNA in fep directory
- Add support for reading fep file in spatial/vector
- Add GeoJSON write support
- Log each SQLite3 statement to debug if "debug" option is passed to URL.
- Support SI units in amplitude and magnitude configuration for `minDist`, `maxDist`,
`minDepth` and `maxDepth`.
```
amplitudes.MLv.maxDist = 8deg
amplitudes.MLv.maxDepth = 80km
```
- Add Catalog support to datamodel.
- magnitudes
- MLc:
- Add correction terms `c6` und `H` for considering vertical distance.
- Consider source depth instead of vertical distance between station
and origin for computing h.
- Add correction terms `c7` and `c8` for exponential decay.
- Update documentation with new style.
- ql2sc
- Add FocalMechanismReference to event for the preferred focal mechanism to
force association.
- GUI
- Add Qt6 support
- EventLists support passing the IDs of events in selected rows to an
external script which can be configured with `eventlist.scripts.export`.
- Add CSV table header information when exporting from the event list.
- Hypocentral instead of epicentral distances may be shown if configured
with `scheme.distanceHypocentral`.
- Allow map zooming with shift + left mouse + dragging.
- Fix segmentation fault if the magnitude table should be sorted and
station magnitudes could not be found in the database or memory.
- Save map measurements as GeoJSON
- Add support for built-in FontAwesome icons as map symbols.
- Print map symbols in map legends.
- scesv
- Support station annotations (shift+F9).
- scolv
- Attempt to fix a crash that is indicated by the terminal output:
- Focal mechanisms show the station distribution on the map if station
display is enabled (F9).
- Add LQT rotation to picker.
- Fix bug in picker when hidden unassociated picks become visible again after
transferring a solution to the locator window.
- If `olv.locator.presetFromOrigin = true` then the locator will be selected
according to the methodID and earthModelID. If that is not found then
the default locator will be set again rather than keeping the last selection.
- Set OriginLocatorView depth type to "depth type set by locator" when
presetFromOrigin is true and the depth type is unset, resetting the state of
the origin set before.
- Add tooltip with attribute content to method and earthModel label to
allow inspecting long strings which do not fit into the label itself.
- Add more flexible "Add station" dialog in picker which allows to filter
identifiers, network and station types and sensor units.
- Add more option to control initial picker behaviour.
```
QThread: Destroyed while thread is still running
picker.rotation = ZRT
picker.unit = Velocity
picker.limitFilterToZoomTrace = true
olv.loadAdditionalStations = true
```
## 6.8.1
- scconfig
- Allow parenthesis as profile names, e.g. for amplitude
profiles.
## 6.8.0
- NonLinLoc locator plugin
- Allow `SAVE_NLLOC_EXPECTATION` in NLL configuration
files.
- Increase precision to milliseconds for the following picker configuration values:
- `picker.preOffset`
- `picker.postOffset`
- `picker.minimumTimeWindow`
- Add `picker.auxiliary.profile` which supports multiple profiles to define
and check for auxiliary channels.
- Add controls to explicitly load auxiliary profiles
- Add controls to toggle visibility of auxiliary profiles
- Add spectrogram settings like in `scrttv` in a dockable widget (ctrl+shift+s) and
remove the very basic spectrogram settings from the toolbar.
- Add optional allow-/denylist for phases to be imported to ImportPicks dialog.
- Add default configuration options for "Import picks" dialog.
- scmv
- Handle unset origin.depth and do not crash.
- fdsnxml2inv
- Set default start date to 1902-01-01 rather than 1980-01-01 if a start
date is not specified for the StationXML node.
- Use best precision when showing number differences in warnings.
- scamp
- Add command-line option `--formatted` for generating formatted XML along
with `--ep`.
- scautoloc
- Add command-line option `--formatted` for generating formatted XML along
with `--ep`.
- scautopick
- Add command-line option `--formatted` for generating formatted XML along
with `--ep`.
- scdb
- Add option `-x` to wipe out all child objects of a public object from
database. This option might make the most sense on `Inventory`,
`EventParameters` or `Config`.
```
$ scdb -d localhost -x Inventory
```
- scevent
- Add command-line option `--formatted` for generating formatted XML along
with `--ep`.
- Add command-line option `--reprocess` for ignoring event objects in
input along with `--ep`.
- Add `eventAssociation.enablePreferredFMSelection` option to control
whether the preferred focalmechanism should be assigned automatically
or not.
- scmag
- Add command-line option `--formatted` for generating formatted XML along
with `--ep`.
- Fix segmentation fault when processing arrivals without distance.
- screpick
- Add command-line option `--formatted` for generating formatted XML along
with `--ep`.
- scdumpobject
- Tool removed entirely. The functionality has been added to scxmldump.
- scxmldump
- Add `--public-id` and `--with-childs` to export an object by its publicID
from the database. This will even work with database extensions by
loading the corresponding plugins such as `dmsm`.
- scwfparam
- Add support for custom list of periods.
- LocSAT
- Fix bug when a function with only one sample is
interpolated. That usually lead to location
errors such as "SVD routine can't decompose matrix".
- Rewrite old old code to support reentrant processing and dynamic station
count.
- Improve performance.
- Add PKiKP and PKIKP phases.
- Update PKKP table.
- Support custom phase list via [model].ph file.
- NLL
- Allow the use of SAVE_NLLOC_EXPECTATION.
- iLoc
- When reading a local velocity model file, If CONRAD is not specified,
the index of the Conrad discontinuity was not set properly, therefore iLoc
assumed the very first depth as the Conrad thus preventing the calculation
of Pg/Sg phases. The calculation of travel times from a local velocity model
was restricted to up to 6 degree distance.
The Conrad discontinuity is no longer set to the surface when CONRAD is not
specified in the local velocity model. Travel-time calculations from local
velocity models now extended to 10 degrees.
- Add `iLoc.usePickUncertainties` and `iLoc.defaultTimeError` to description.
- doc
- Replace Sphinx m2r2 with sphinx_mdinclude
- diskmon
- Fix stopped modules counter for diskmon.
## 6.7.9
@ -244,6 +363,9 @@ will be tackled in future updates.
- Allow to disable SQLite3 disc syncrhronization to decrease time needed to
save data in an SQLite3 database: `sqlite3:///path/to/file?sync=false`.
- Add support for all synchronous flags of SQLite3 (`sync=[normal|full|extra]`).
- Add option `amplitudes.[type].considerUnusedArrivals` which if enabled
considers stations with unused (disabled) arrivals for amplitude and
implicitly magnitude computations. Affects scamp, scmag and scolv.
- scolv
- Replace operator comment input control with a text edit control which
allows new lines. Furthermore the restriction of 160 characters has been

6
share/doc/seiscomp/html/_sources/base/api-python-client.rst.txt
View File

@ -123,7 +123,7 @@ and configure it in the constructor.
As marked in line 4, the call of the constructor of the base class is very
important. It takes the command line parameters and sets up internal
application variables. Without this call the application will either not run
at all or show undefined/unexpected behaviour.
at all or show undefined/unexpected behavior.
The constructor takes also the initial parameters of the application such as
enabling a messaging connection and enabling database access.
@ -155,7 +155,7 @@ All application methods are defined in the C++ header file
Init
^^^^
The workflow of the init function looks like this:
The workflow of the :func:`init` function looks like this:
.. code-block:: python
@ -394,7 +394,7 @@ returns the RecordStream instance which can be used to add stream requests.
The record stream service is configured either with configuration files
(:confval:`recordstream`) or
via command-line options ``-I`, ``--record-url``.
via the command-line option ``-I, --record-url``.
The application finishes if the record stream read EOF. Running a :class:`StreamApplication`
with :ref:`Seedlink<seedlink>` would probably never terminate since it is a

423
share/doc/seiscomp/html/_sources/base/api-python.rst.txt
View File

@ -47,10 +47,12 @@ EventParameters
MomentTensorPhaseSetting [label="MomentTensorPhaseSetting", href="../base/api-python.html#api-python-datamodel-momenttensorphasesetting", target="_top"]
MomentTensorStationContribution [label="MomentTensorStationContribution", href="../base/api-python.html#api-python-datamodel-momenttensorstationcontribution", target="_top"]
MomentTensorComponentContribution [label="MomentTensorComponentContribution", href="../base/api-python.html#api-python-datamodel-momenttensorcomponentcontribution", target="_top"]
Catalog [label="Catalog", href="../base/api-python.html#api-python-datamodel-catalog", target="_top"]
Event [label="Event", href="../base/api-python.html#api-python-datamodel-event", target="_top"]
EventDescription [label="EventDescription", href="../base/api-python.html#api-python-datamodel-eventdescription", target="_top"]
OriginReference [label="OriginReference", href="../base/api-python.html#api-python-datamodel-originreference", target="_top"]
FocalMechanismReference [label="FocalMechanismReference", href="../base/api-python.html#api-python-datamodel-focalmechanismreference", target="_top"]
Event [label="Event", href="../base/api-python.html#api-python-datamodel-event", target="_top"]
EventParameters [label="EventParameters", href="../base/api-python.html#api-python-datamodel-eventparameters", target="_top"]
EventParameters -> Pick [dir=back arrowtail=diamond]
MomentTensor -> Comment [dir=back arrowtail=diamond]
@ -60,6 +62,7 @@ EventParameters
StationMagnitude -> Comment [dir=back arrowtail=diamond]
Pick -> Comment [dir=back arrowtail=diamond]
Event -> Comment [dir=back arrowtail=diamond]
Catalog -> Comment [dir=back arrowtail=diamond]
Origin -> Comment [dir=back arrowtail=diamond]
EventParameters -> Amplitude [dir=back arrowtail=diamond]
EventParameters -> Reading [dir=back arrowtail=diamond]
@ -77,10 +80,14 @@ EventParameters
MomentTensor -> MomentTensorPhaseSetting [dir=back arrowtail=diamond]
MomentTensor -> MomentTensorStationContribution [dir=back arrowtail=diamond]
MomentTensorStationContribution -> MomentTensorComponentContribution [dir=back arrowtail=diamond]
EventParameters -> Catalog [dir=back arrowtail=diamond]
Catalog -> Event [dir=back arrowtail=diamond]
EventParameters -> Event [dir=back arrowtail=diamond]
Event -> EventDescription [dir=back arrowtail=diamond]
Event -> OriginReference [dir=back arrowtail=diamond]
Event -> FocalMechanismReference [dir=back arrowtail=diamond]
Catalog -> Event [dir=back arrowtail=diamond]
EventParameters -> Event [dir=back arrowtail=diamond]
}
.. graphviz::
@ -477,6 +484,27 @@ EventParameters
href = "../base/api-python.html#api-python-datamodel-momenttensorcomponentcontribution"
target = "_top"
]
Catalog [
labeltooltip = "Catalog"
label = <
<table border="0" cellpadding="0" cellspacing="2">
<tr><td>Catalog</td></tr>
<hr/>
<tr><td> </td></tr>
<tr><td align="left" port="publicID"><font color="#8b0000">+ publicID: string</font></td></tr>
<tr><td align="left" port="name"><font color="#8b0000">+ name: string</font></td></tr>
<tr><td align="left" port="description"><font color="#8b0000">+ description: string</font></td></tr>
<tr><td align="left" port="creationInfo"><font color="#8b0000">+ creationInfo: CreationInfo [0..1]</font></td></tr>
<tr><td align="left" port="start"><font color="#8b0000">+ start: datetime</font></td></tr>
<tr><td align="left" port="end"><font color="#8b0000">+ end: datetime [0..1]</font></td></tr>
<tr><td align="left" port="dynamic"><font color="#8b0000">+ dynamic: boolean</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ comment: Comment [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ event: Event [0..*]</font></td></tr>
</table>
>
href = "../base/api-python.html#api-python-datamodel-catalog"
target = "_top"
]
Event [
labeltooltip = "Event"
label = <
@ -540,6 +568,29 @@ EventParameters
href = "../base/api-python.html#api-python-datamodel-focalmechanismreference"
target = "_top"
]
Event [
labeltooltip = "Event"
label = <
<table border="0" cellpadding="0" cellspacing="2">
<tr><td>Event</td></tr>
<hr/>
<tr><td> </td></tr>
<tr><td align="left" port="publicID"><font color="#8b0000">+ publicID: string</font></td></tr>
<tr><td align="left" port="preferredOriginID"><font color="#8b0000">+ preferredOriginID: string</font></td></tr>
<tr><td align="left" port="preferredMagnitudeID"><font color="#8b0000">+ preferredMagnitudeID: string</font></td></tr>
<tr><td align="left" port="preferredFocalMechanismID"><font color="#8b0000">+ preferredFocalMechanismID: string</font></td></tr>
<tr><td align="left" port="type"><font color="#8b0000">+ type: EventType [0..1]</font></td></tr>
<tr><td align="left" port="typeCertainty"><font color="#8b0000">+ typeCertainty: EventTypeCertainty [0..1]</font></td></tr>
<tr><td align="left" port="creationInfo"><font color="#8b0000">+ creationInfo: CreationInfo [0..1]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ eventDescription: EventDescription [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ comment: Comment [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ originReference: OriginReference [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ focalMechanismReference: FocalMechanismReference [0..*]</font></td></tr>
</table>
>
href = "../base/api-python.html#api-python-datamodel-event"
target = "_top"
]
EventParameters [
labeltooltip = "EventParameters"
label = <
@ -553,6 +604,7 @@ EventParameters
<tr><td align="left"><font color="#8b0000">+ reading: Reading [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ origin: Origin [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ focalMechanism: FocalMechanism [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ catalog: Catalog [0..*]</font></td></tr>
<tr><td align="left"><font color="#8b0000">+ event: Event [0..*]</font></td></tr>
</table>
>
@ -567,6 +619,7 @@ EventParameters
StationMagnitude -> Comment [dir=back arrowtail=diamond]
Pick -> Comment [dir=back arrowtail=diamond]
Event -> Comment [dir=back arrowtail=diamond]
Catalog -> Comment [dir=back arrowtail=diamond]
Origin -> Comment [dir=back arrowtail=diamond]
EventParameters -> Amplitude [dir=back arrowtail=diamond]
EventParameters -> Reading [dir=back arrowtail=diamond]
@ -584,10 +637,14 @@ EventParameters
MomentTensor -> MomentTensorPhaseSetting [dir=back arrowtail=diamond]
MomentTensor -> MomentTensorStationContribution [dir=back arrowtail=diamond]
MomentTensorStationContribution -> MomentTensorComponentContribution [dir=back arrowtail=diamond]
EventParameters -> Catalog [dir=back arrowtail=diamond]
Catalog -> Event [dir=back arrowtail=diamond]
EventParameters -> Event [dir=back arrowtail=diamond]
Event -> EventDescription [dir=back arrowtail=diamond]
Event -> OriginReference [dir=back arrowtail=diamond]
Event -> FocalMechanismReference [dir=back arrowtail=diamond]
Catalog -> Event [dir=back arrowtail=diamond]
EventParameters -> Event [dir=back arrowtail=diamond]
}
@ -5475,6 +5532,280 @@ Blob
:rtype: string
.. _api-python-datamodel-catalog:
Catalog
............................................................
.. py:class:: Catalog
Inherits :ref:`PublicObject <api-python-datamodel-publicobject>`.
**Parents**:
- ``eventParameters`` -- :ref:`EventParameters <api-python-datamodel-eventparameters>`
**Children**:
- ``comment`` -- :ref:`Comment <api-python-datamodel-comment>`
- ``event`` -- :ref:`Event <api-python-datamodel-event>`
**Attributes**:
- ``publicID``: string
- ``name`` -- string
- ``description`` -- string
- ``creationInfo`` -- :ref:`CreationInfo <api-python-datamodel-creationinfo>` (optional)
- ``start`` -- seiscomp.core.Time
- ``end`` -- seiscomp.core.Time (optional)
- ``dynamic`` -- boolean
**Methods**:
.. py:staticmethod:: Cast(obj)
:param obj: The object to be casted.
:rtype: An object of type Catalog if the cast was successful,
None otherwise.
Cast an arbitrary object to Catalog if the internal wrapped
representation is an Catalog object. The cast is important if
instances of type :ref:`Object <api-python-datamodel-object>`
are passed to methods which need access to the real type.
.. py:staticmethod:: Create()
:rtype: A new object of type Catalog.
Creates and registers (if enabled) a Catalog instance. The
publicID is auto-generated.
.. py:staticmethod:: Create(publicID)
:rtype: A new object of type Catalog.
Creates and registers (if enabled) a Catalog instance with
passed publicID.
.. py:method:: equal(other)
:param other: Another object of type Catalog to compare this
instance to
:rtype: A Boolean value indicating True if both objects are equal or
False otherwise.
Compares two objects without its child objects. Both objects are compared
by value.
.. py:method:: setName(name)
:param name: string
.. py:method:: name()
:rtype: string
.. py:method:: setDescription(description)
:param description: string
Catalog description
.. py:method:: description()
:rtype: string
.. py:method:: setCreationInfo(creationInfo)
:param creationInfo: :ref:`CreationInfo <api-python-datamodel-creationinfo>`
CreationInfo for the Catalog object.
.. py:method:: creationInfo()
:rtype: :ref:`CreationInfo <api-python-datamodel-creationinfo>`
.. note::
As this attribute is optional, this method throws a ValueError if
the value of the attribute is not set.
.. py:method:: setStart(start)
:param start: seiscomp.core.Time
Start of epoch in ISO datetime format
.. py:method:: start()
:rtype: seiscomp.core.Time
.. py:method:: setEnd(end)
:param end: seiscomp.core.Time
End of epoch \(empty if the catalog epoch is open\)
.. py:method:: end()
:rtype: seiscomp.core.Time
.. note::
As this attribute is optional, this method throws a ValueError if
the value of the attribute is not set.
.. py:method:: setDynamic(dynamic)
:param dynamic: boolean
.. py:method:: dynamic()
:rtype: boolean
.. py:method:: add(comment)
:param comment: Object of type :ref:`Comment <api-python-datamodel-comment>`
:rtype: A Boolean value indicating success with True, False otherwise.
Adds a Comment object to Catalog. The object is not
copied but managed by this instance. Any change to the passed object
will also change the child.
.. py:method:: add(event)
:param event: Object of type :ref:`Event <api-python-datamodel-event>`
:rtype: A Boolean value indicating success with True, False otherwise.
Adds a Event object to Catalog. The object is not
copied but managed by this instance. Any change to the passed object
will also change the child.
.. py:method:: remove(comment)
:param comment: Object of type :ref:`Comment <api-python-datamodel-comment>`
:rtype: A Boolean value indicating success with True, False otherwise.
Removes a previously added Comment object from Catalog.
.. py:method:: remove(event)
:param event: Object of type :ref:`Event <api-python-datamodel-event>`
:rtype: A Boolean value indicating success with True, False otherwise.
Removes a previously added Event object from Catalog.
.. py:method:: removeComment(idx)
:param idx: An integer index of the object to be removed.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: removeComment(commentIndex);
:param commentIndex: The index of the object to be removed of type CommentIndex.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: removeEvent(idx)
:param idx: An integer index of the object to be removed.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: commentCount()
:rtype: integer value indicating the number of child objects.
Returns the number of Comment child objects.
.. py:method:: eventCount()
:rtype: integer value indicating the number of child objects.
Returns the number of Event child objects.
.. py:method:: comment(idx)
:param idx: An integer index of the object to be returned.
:rtype: Object of type :ref:`Comment <api-python-datamodel-comment>`.
Returns the Comment at index idx.
.. py:method:: comment(commentIndex)
:param commentIndex: The index of the object to be removed of type CommentIndex.
:rtype: Object of type :ref:`Comment <api-python-datamodel-comment>`.
Returns the Comment at given index. The indexes of all child objects
are compared by value which makes this function slower than the direct
integer index look-up.
.. py:method:: event(idx)
:param idx: An integer index of the object to be returned.
:rtype: Object of type :ref:`Event <api-python-datamodel-event>`.
Returns the Event at index idx.
.. py:method:: findEvent(publicID)
:param publicID: The publicID of the object to find.
:rtype: Object of type :ref:`Event <api-python-datamodel-event>`.
Returns the child object with a certain publicID, None otherwise.
.. py:method:: eventParameters()
:rtype: EventParameters
Returns the parent EventParameters if available. Returns None
if the parent is not a EventParameters. This is a convenience wrapper
for parent().
.. py:method:: assign(other)
This method implements the :ref:`Object <api-python-datamodel-object>` interface.
.. py:method:: attachTo(parent)
This method implements the :ref:`Object <api-python-datamodel-object>` interface.
.. py:method:: detachFrom(parent)
This method implements the :ref:`Object <api-python-datamodel-object>` interface.
.. py:method:: detach()
This method implements the :ref:`Object <api-python-datamodel-object>` interface.
.. py:method:: clone()
:rtype: A cloned Catalog.
Returns a new instance that is a clone of the current instance. Child
objects are being ignored.
.. py:method:: updateChild(ref)
:param ref: A child object derived from class Object.
:rtype: A Boolean flag indicating success with True, False otherwise
This method takes the passed reference object and searches for a child
with the same publicID (if derived from :ref:`PublicObject <api-python-datamodel-publicobject>`)
or the same index (if derived from :ref:`Object <api-python-datamodel-object>`).
The the child was found the reference objects attributes are copied to
the child object. Children of child are being ignored during this operation.
This method implements the :ref:`PublicObject <api-python-datamodel-publicobject>` interface.
.. py:method:: accept(visitor)
:param visitor: A visitor.
This method implements the :ref:`PublicObject <api-python-datamodel-publicobject>` interface.
.. _api-python-datamodel-comment:
Comment
@ -5496,6 +5827,7 @@ Comment
- ``stationMagnitude`` -- :ref:`StationMagnitude <api-python-datamodel-stationmagnitude>`
- ``pick`` -- :ref:`Pick <api-python-datamodel-pick>`
- ``event`` -- :ref:`Event <api-python-datamodel-event>`
- ``catalog`` -- :ref:`Catalog <api-python-datamodel-catalog>`
- ``origin`` -- :ref:`Origin <api-python-datamodel-origin>`
- ``parameter`` -- :ref:`Parameter <api-python-datamodel-parameter>`
- ``parameterSet`` -- :ref:`ParameterSet <api-python-datamodel-parameterset>`
@ -5671,6 +6003,14 @@ Comment
if the parent is not a Event. This is a convenience wrapper
for parent().
.. py:method:: catalog()
:rtype: Catalog
Returns the parent Catalog if available. Returns None
if the parent is not a Catalog. This is a convenience wrapper
for parent().
.. py:method:: origin()
:rtype: Origin
@ -6764,6 +7104,7 @@ CreationInfo
- :func:`Amplitude.creationInfo`
- :func:`Arrival.creationInfo`
- :func:`Catalog.creationInfo`
- :func:`Comment.creationInfo`
- :func:`ConfigStation.creationInfo`
- :func:`Event.creationInfo`
@ -8495,6 +8836,7 @@ Event
**Parents**:
- ``catalog`` -- :ref:`Catalog <api-python-datamodel-catalog>`
- ``eventParameters`` -- :ref:`EventParameters <api-python-datamodel-eventparameters>`
**Children**:
@ -8821,6 +9163,14 @@ Event
are compared by value which makes this function slower than the direct
integer index look-up.
.. py:method:: catalog()
:rtype: Catalog
Returns the parent Catalog if available. Returns None
if the parent is not a Catalog. This is a convenience wrapper
for parent().
.. py:method:: eventParameters()
:rtype: EventParameters
@ -9009,6 +9359,7 @@ EventParameters
- ``reading`` -- :ref:`Reading <api-python-datamodel-reading>`
- ``origin`` -- :ref:`Origin <api-python-datamodel-origin>`
- ``focalMechanism`` -- :ref:`FocalMechanism <api-python-datamodel-focalmechanism>`
- ``catalog`` -- :ref:`Catalog <api-python-datamodel-catalog>`
- ``event`` -- :ref:`Event <api-python-datamodel-event>`
**Attributes**:
@ -9085,6 +9436,15 @@ EventParameters
copied but managed by this instance. Any change to the passed object
will also change the child.
.. py:method:: add(catalog)
:param catalog: Object of type :ref:`Catalog <api-python-datamodel-catalog>`
:rtype: A Boolean value indicating success with True, False otherwise.
Adds a Catalog object to EventParameters. The object is not
copied but managed by this instance. Any change to the passed object
will also change the child.
.. py:method:: add(event)
:param event: Object of type :ref:`Event <api-python-datamodel-event>`
@ -9129,6 +9489,13 @@ EventParameters
Removes a previously added FocalMechanism object from EventParameters.
.. py:method:: remove(catalog)
:param catalog: Object of type :ref:`Catalog <api-python-datamodel-catalog>`
:rtype: A Boolean value indicating success with True, False otherwise.
Removes a previously added Catalog object from EventParameters.
.. py:method:: remove(event)
:param event: Object of type :ref:`Event <api-python-datamodel-event>`
@ -9161,6 +9528,11 @@ EventParameters
:param idx: An integer index of the object to be removed.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: removeCatalog(idx)
:param idx: An integer index of the object to be removed.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: removeEvent(idx)
:param idx: An integer index of the object to be removed.
@ -9196,6 +9568,12 @@ EventParameters
Returns the number of FocalMechanism child objects.
.. py:method:: catalogCount()
:rtype: integer value indicating the number of child objects.
Returns the number of Catalog child objects.
.. py:method:: eventCount()
:rtype: integer value indicating the number of child objects.
@ -9237,6 +9615,13 @@ EventParameters
Returns the FocalMechanism at index idx.
.. py:method:: catalog(idx)
:param idx: An integer index of the object to be returned.
:rtype: Object of type :ref:`Catalog <api-python-datamodel-catalog>`.
Returns the Catalog at index idx.
.. py:method:: event(idx)
:param idx: An integer index of the object to be returned.
@ -9279,6 +9664,13 @@ EventParameters
Returns the child object with a certain publicID, None otherwise.
.. py:method:: findCatalog(publicID)
:param publicID: The publicID of the object to find.
:rtype: Object of type :ref:`Catalog <api-python-datamodel-catalog>`.
Returns the child object with a certain publicID, None otherwise.
.. py:method:: findEvent(publicID)
:param publicID: The publicID of the object to find.
@ -15138,23 +15530,14 @@ QCLog
Compares two objects without its child objects. Both objects are compared
by value.
.. py:method:: index()
:rtype: The object's index of type QCLogIndex.
Returns the objects index which is also used for the database as unique
constraint.
.. py:method:: equalIndex(lhs)
:param lhs: :ref:`QCLog <api-python-datamodel-qclog>`
:rtype: A Boolean value indicating True if both indexes are equal or
False otherwise.
.. py:method:: setWaveformID(waveformID)
:param waveformID: :ref:`WaveformStreamID <api-python-datamodel-waveformstreamid>`
The waveform identifier for which the annotation is valid. Each component
can contain wildcards \(asterisk or question mark\) but no regular
expressions.
.. py:method:: waveformID()
:rtype: :ref:`WaveformStreamID <api-python-datamodel-waveformstreamid>`
@ -15348,11 +15731,6 @@ QualityControl
:param idx: An integer index of the object to be removed.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: removeQCLog(qCLogIndex);
:param qCLogIndex: The index of the object to be removed of type QCLogIndex.
:rtype: A Boolean value indicating success with True, False otherwise.
.. py:method:: removeWaveformQuality(idx)
:param idx: An integer index of the object to be removed.
@ -15398,15 +15776,6 @@ QualityControl
Returns the QCLog at index idx.
.. py:method:: qCLog(qCLogIndex)
:param qCLogIndex: The index of the object to be removed of type QCLogIndex.
:rtype: Object of type :ref:`QCLog <api-python-datamodel-qclog>`.
Returns the QCLog at given index. The indexes of all child objects
are compared by value which makes this function slower than the direct
integer index look-up.
.. py:method:: waveformQuality(idx)
:param idx: An integer index of the object to be returned.

30
share/doc/seiscomp/html/_sources/base/build.rst.txt
View File

@ -98,26 +98,30 @@ a build directory, configure the build and start it:
Software dependencies
=====================
For compiling the |scname| sources the following development software packages
are required (Debian/Ubuntu package names):
For compiling the |scname| sources the development software packages must be
installed by Linux system commands such as :program:`apt` or :program:`dnf`.
The required packages are (Debian/Ubuntu package names):
* flex
* g++
* git
* cmakecmake-gui
* crypto-dev
* libboost
* libxml2-dev
* flex
* libbson-dev
* libfl-dev
* libssl-dev
* crypto-dev
* python3-dev (optional)
* python3-numpy (optional, required if Numpy support is enabled which is also the default configuration)
* libqt5-dev (optional)
* qtbase5-dev (optional)
* libmysqlclient-dev (optional)
* libpq-dev (optional)
* libsqlite3-dev (optional)
* ncurses-dev (optional)
* libxml2-dev
Optional, depending on the modules to be built are (Debian/Ubuntu package names):
* libmysqlclient-dev
* libpq-dev
* libqt5-dev
* libsqlite3-dev
* ncurses-dev
* python3-dev
* python3-numpy (required if Numpy support is enabled which is also the default configuration)
* qtbase5-dev
As of |scname| in version 5.0.0 support for Python 2 is dropped and Python 3 has
become the default.

19
share/doc/seiscomp/html/_sources/base/coding-conventions.rst.txt
View File

@ -21,6 +21,7 @@ used to fill the space. The recommended tab width is 4 characters.
> if ( a > 5 ) {
> > SEISCOMP_DEBUG("A is greater than 5. Its current value is %d",
> > ...............a);
> }
> return a;
}
@ -84,14 +85,14 @@ C++ code is (or should be) written with the following code style:
}
namespace Foo {
namespace Bar {
namespace Foo::Bar {
void foo(int a, int b) {
for ( int i = 0; i < a; ++i ) {
if ( i < b )
if ( i < b ) {
bar(i);
}
else {
bar(i);
bar(b);
@ -100,8 +101,7 @@ C++ code is (or should be) written with the following code style:
}
} // namespace Bar
} // namespace Foo
} // namespace Foo::Bar
#endif
@ -217,22 +217,25 @@ Check a null pointer with implicit boolean conversion.
.. code-block:: c++
if ( !ptr )
if ( !ptr ) {
do_something();
}
rather than
.. code-block:: c++
if ( ptr == 0 )
if ( ptr == 0 ) {
do_something();
}
or
.. code-block:: c++
if ( ptr == NULL )
if ( ptr == NULL ) {
do_something();
}
Virtual Functions
=================

2
share/doc/seiscomp/html/_sources/base/concepts.rst.txt
View File

@ -19,5 +19,5 @@ the :term:`trunk` package.
RecordStream: Access to data from real-time servers or archives </base/concepts/recordstream>
Inventory: Station meta data </base/concepts/inventory>
Configuration: Inventory, module and binding configurations </base/concepts/configuration>
Processing: Magnitude computation </base/concepts/magnitudes>
Processing: Amplitudes and magnitudes </base/concepts/magnitudes>
Processing: Locator types </base/concepts/locators>

9
share/doc/seiscomp/html/_sources/base/concepts/locators.rst.txt
View File

@ -11,7 +11,7 @@ further.
|scname| ships with built-in locators:
* :ref:`FixedHypocenter <global_fixedhypocenter>` (FH)
* :ref:`FixedHypocenter <global_fixedhypocenter>`
* :ref:`Hypo71 <global_hypo71>`
* :ref:`iLoc <global_iloc>`
* :ref:`LOCSAT <global_locsat>`, the default locator in :ref:`scautoloc` and :ref:`scolv`
@ -41,13 +41,14 @@ A comparison of the locators is given in the table below.
.. csv-table::
:widths: 30 10 10 10 10 10 10 10
:header: , FH, Hypo71, iLoc, LocExt, LOCSAT, NonLinLoc, StdLoc
:header: , Fixed Hypocenter, Hypo71, iLoc, LocExt, LOCSAT, NonLinLoc, StdLoc
:align: center
**Applications**, ,,,,,,
phases considered by default, seismic / infrasound, seismic, seismic / infrasound / hydroacoustic, [3], seismic / infrasound, seismic, seismic
distance ranges of application, local / regional / teleseismic, local / regional, local / regional / teleseismic, [3], local / regional / teleseismic, local / regional / teleseismic, local / regional [4]
application with default configuration, regional / teleseismic, ❌, regional / global, [3], regional / teleseismic, ❌, local / regional [1]
origin depth range, [4], non-negative, 0 - 700 km, [3], 0 - 800 km, full range depending on travel-time tables, [4]
**Algorithm**, ,,,,,,
inversion algorithm, linear, iterative, configurable, [3], grid search, probabilistic, configurable
automatic phase renaming, ❌, ❌, ✅, [3], ❌, ❌, ❌
@ -59,7 +60,7 @@ A comparison of the locators is given in the table below.
considers pick backazimuth, ❌, ❌, ✅, [3], ✅, ❌, ❌
speed, fast, fast, fast - intermediate, [3], fast, intermediate, fast - intermediate
**Velocity model**, ,,,,,,
velocity model, 1D [4], 1D, 1D, [3],1D, 1D / 3D, 1D / 3D [4]
velocity model, 1D [4], 1D, 1D / local adjustments, [3], 1D, 1D / 3D, 1D / 3D [4]
independent Vp and Vs, ✅ [4], ❌, ✅, [3], ✅, ✅, ✅ [4]
default velocity model, iasp91 / tab, ❌, iasp91 / ak135, [3], iasp91 / tab, ❌, iasp91 / tab [1]
applies RSTT, ❌ , ❌, ✅, [3], ❌, ❌, ❌
@ -74,7 +75,7 @@ A comparison of the locators is given in the table below.
operates without custom scripts, ✅, ✅, ✅, ❌, ✅, ✅, ✅
**Others**, ,,,,,,
remarks, intended for ground-truth tests / single-station location / any travel-time interface, ,operational at EMSC and ISC (earlier version), any external locator can be called by a custom script, currently the fastest locator in |scname| and the only one available to :ref:`scautoloc`, considers model uncertainties, uses travel-times from any travel-time interface
point of contact, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, `ibondar2014 @gmail.com <ibondar2014@gmail.com>`_, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`
point of contact, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, `istvan.bondar @slsiloc.eu <istvan.bondar@slsiloc.eu>`_, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`
* [1]: requires initial or specific configuration
* [2]: requires correction file

205
share/doc/seiscomp/html/_sources/base/concepts/magnitudes.rst.txt
View File

@ -1,34 +1,85 @@
.. _concepts_magnitudes:
Magnitudes
##########
Amplitudes and Magnitudes
#########################
Magnitudes are computed based on amplitudes measured from waveforms. Different
types of amplitudes and magnitudes are available which are listed in
:ref:`scamp` and :ref:`scmag`.
:ref:`Magnitudes of specific types <concepts_magnitudes-station>` are computed
from :ref:`amplitudes <concepts_magnitudes-amplitudes>` measured on waveforms.
Different types of amplitudes and magnitudes are available including aliases.
All magnitudes can be regionalized and mapped to Mw. The native amplitude and
magnitudes types are listed in :ref:`scamp` and :ref:`scmag`.
All amplitude and magnitude values can be read in the Magnitudes tab of
:ref:`scolv`, in bulletins created by :ref:`scbulletin` and dumped
from database to XML for an origin or event by :ref:`scxmldump`.
This concept section describes the principles applied in |scname| and links to
more specific sections including tutorials describing the configuration and
application.
.. figure:: media/amplitude-magnitude-processing.png
:alt: amplitudes and magnitudes: processing flow
:align: center
:width: 18cm
Schematic processing flow for computing magnitudes from measured amplitudes
including the involved |scname| modules and interfaces. Multiple network
magnitude types can be computed for the same :term:`origin`. The default
processing of native amplitudes and magnitudes in the center can be extended
by aliases, regionalization, Mw mapping or external magnitudes.
.. _concepts_magnitudes-amplitudes:
Amplitudes
==========
Amplitudes can be measured automatically from waveforms
Amplitudes can be measured on waveforms
* During phase picking by :ref:`scautopick` with generally fixed time windows
due to the absence of knowledge about source parameters or by,
* :ref:`scamp` as soon as :term:`origins <origin>` are available. Depending
on the magnitude type, fixed or distance-dependent time windows apply.
* Automatically during phase picking by :ref:`scautopick` with generally fixed
time windows due to the absence of knowledge about source parameters.
* Automatically by :ref:`scamp` as soon as :term:`origins <origin>` are
available. Depending on the amplitude type and their configuration, fixed or
distance-dependent time windows as well as constraints on signal quality apply.
* Interactively using :ref:`scolv` with preset or user-defined conditions.
and interactively using :ref:`scolv`.
:ref:`Time grammar <time-grammar>` applies for configuring the time windows.
Instrument simulation
---------------------
Input data
----------
Amplitude measurements for some magnitude types require or allow the simulation
Depending on type amplitudes are measured on raw or filtered waveform data.
Initial raw data are given in counts of the digitizer with a stream gain unit of
m/s which is typical for seismometers.
It is assumed that the measured signal has its dominant
frequency where the response of the recording instrument is flat.
For other instruments such as accelerometers or short-period geophones, amplitude
correction for instrument response and the corresponding frequency range may be
configured by the global binding parameters
:confval:`amplitudes.enableResponses`, :confval:`amplitudes.resp.minFreq`,
:confval:`amplitudes.resp.maxFreq` or even with in amplitude-type profiles for
more specific application. Amplitude measurements will fail if the
unit of the (corrected) input data do not correspond to the requirement of the
amplitude type.
Filtering may involve
:ref:`simulation of Wood-Anderson seismographs <concepts_magnitudes-wa>`.
Final amplitude measurements are corrected by stream gain and provided as an
amplitude object.
.. _concepts_magnitudes-wa:
Wood-Anderson simulation
------------------------
Some amplitude types require or allow the correction of waveforms by simulation
of instruments such as :py:func:`Wood-Anderson torsion seismometers <WA>`
(:cite:t:`richter-1935,uhrhammer-1990`), :py:func:`WWSSN_SP` or :py:func:`WWSSN_LP`.
The calibration parameters describing the Wood-Anderson seismometer are
configurable in global bindings or global module configuration:
The calibration parameters describing a Wood-Anderson seismometer are
configurable in global bindings or module configuration:
:confval:`amplitudes.WoodAnderson.gain`, :confval:`amplitudes.WoodAnderson.T0`,
:confval:`amplitudes.WoodAnderson.h`. Specifically, the difference in magnitude
due to configuration using original values listed in
@ -38,16 +89,61 @@ Wood-Anderson simulation, e.g. :term:`ML <magnitude, local (ML)>`,
:term:`MLv <magnitude, local vertical (MLv)>`, :term:`MLc <magnitude, local custom (MLc)>`.
Physical units
--------------
The physical units of measured amplitudes depend on amplitudes type. They are
documented along with the corresponding magnitude type. Starting with the initial
gain unit of raw data streams, typically m/s, the amplitude processor in
|scname| converts to the required unit. Where instrument simulation if optional,
e.g., for :term:`MLc amplitudes <magnitude, local custom (MLc)>`, a conversion
configurable factor must be considered for non-default amplitude processing.
.. _concepts_amplitudes-aliases:
Amplitude Aliases
-------------------------------
New amplitude types (aliases) can be created based on existing amplitude types
but configured and measured specifically. They can be measured as any other
amplitude by :ref:`scamp` or :ref:`scautopick` and used by other modules, e.g.,
by :ref:`scmag` for :ref:`magnitude aliases <concepts_magnitudes-station>`. The
setup procedure is outlined in the tutorial on
:ref:`amplitude aliases <tutorials_amplitude-aliases>`.
.. _concepts-amplitudes-regionalization:
Regionalization
---------------
Measuring amplitudes only for sources or pairs of sources and stations in
specific regions is supported by regionalization. The region polygons are
defined by :ref:`magnitude regionalization <concepts-magnitudes-regionalization>`.
In order to use the feature, regionalized amplitudes and magnitudes must have
the same type (name) and regionalization must be activated per amplitude type in
amplitude-type profiles of global bindings.
.. _concepts_magnitudes-station:
Station Magnitudes
==================
Station magnitudes are computed automatically by :ref:`scmag` or interactively
by :ref:`scolv` from measured amplitudes based on distance-dependent
calibration curves which depend on magnitude type. When computing a set of
magnitudes in :ref:`scolv` which is different from the set configured in
:ref:`scmag`, then scmag may later add the missing magnitudes automatically.
Magnitude types for which the evaluation status is set to "rejected", e.g., in
scolv, will not be recomputed by scmag.
calibration curves which depend on magnitude type. Since distance measures are
required, station magnitudes are always related to one :term:`origin`. For
computing new magnitudes in scolv, a new origin must be created which is done by
relocating.
When computing a set of station magnitudes in :ref:`scolv` which is different from
the set configured in :ref:`scmag`, then scmag may later add the missing
magnitudes automatically. Magnitude types for which the evaluation status is
set to "rejected", e.g., in :ref:`scolv`, will not be recomputed by scmag. In
order to ignore a magnitude type interactively, it should therefore be treated
and rejected in scolv.
.. _concepts-magnitudes-correction:
@ -64,7 +160,7 @@ global :ref:`binding parameters <global_bindings_config>`:
When using binding profiles, all referencing stations will be affected equally
which is typically not intended. In contrast, applying station bindings requires
to set up many bindings which may not be intended either.
to set up many bindings which may not be intended either.concepts-magnitudes-regionalization
Therefore, you may add lines to the global module configuration in
:file:`global.cfg` where one line corresponds to one station with one magnitude
@ -85,39 +181,26 @@ parameters are identical to the global bindings parameters. All lines start with
:file:`seiscomp/etc/global.cfg`.
Network Magnitudes
==================
.. _concepts_magnitudes-aliases:
Network magnitudes are computed automatically by :ref:`scmag` or interactively
by :ref:`scolv` from station magnitudes based on averaging station magnitudes.
The averaging methods applied by :ref:`scmag` are configurable by
:confval:`magnitudes.average`. Available are (:cite:t:`rosenberger-1983`):
Magnitude Aliases
-------------------------------
* *mean*: the mean value from all station magnitudes.
* *median*: the mean value from all station magnitudes.
* *trimmedMean(X)*: gnores outlier station magnitudes by first removing the
largest and the smallest *X* % of the observed values (percentiles). The mean is
formed from the remaining station magnitudes.
* *trimmedMedian(X)*: forms the median from all station magnitudes but returns
the uncertainty by ignoring the largest and the smallest *X* % station
magnitudes.
* *medianTrimmedMean(X)*: returns the mean magnitude from all station magnitudes
differing less than *X* magnitudes from the median.
Aliases
=======
New magnitude types (aliases) can be created based on existing magnitude and
amplitude types but configured specifically.
The setup procedure is outlined in the
:ref:`tutorial on magnitude aliases <tutorials_magnitude-aliases>`.
New magnitude types (aliases) can be created inheriting the configuration
parameters but not the configured values from existing magnitude and amplitude types or
:ref:`amplitude aliases <concepts_amplitudes-aliases>`. The values are configured
specifically. Unless specified explicitly, the amplitude type
is the base amplitude of the original magnitude. Other
amplitude types or amplitude aliases must be defined first and given explicitly.
The aliased magnitudes can be computed by other modules such as :ref:`scmag` or
:ref:`scolv`. The setup procedure is outlined in the tutorial on
:ref:`magnitude aliases <tutorials_magnitude-aliases>`.
.. _concepts-magnitudes-regionalization:
Regionalization
===============
---------------
The computation of station magnitudes can be regionalized. This means that for
a specific region specific conditions apply when computing magnitudes. The
@ -135,6 +218,30 @@ setup procedure including
:ref:`tutorial on regionalization <tutorials_magnitude-region-aliases>`.
.. _concepts_magnitudes-network:
Network Magnitudes
==================
Network magnitudes are computed automatically by :ref:`scmag` or interactively
by :ref:`scolv` from station magnitudes based on averaging station magnitudes.
The averaging methods applied by :ref:`scmag` are configurable by
:confval:`magnitudes.average`. Available are (:cite:t:`rosenberger-1983`):
* *mean*: The mean value from all station magnitudes.
* *median*: The mean value from all station magnitudes.
* *trimmedMean(X)*: Ignores outlier station magnitudes by first removing the
largest and the smallest *X* % of the observed values (percentiles). The mean is
formed from the remaining station magnitudes.
* *trimmedMedian(X)*: Forms the median from all station magnitudes but returns
the uncertainty by ignoring the largest and the smallest *X* % station
magnitudes.
* *medianTrimmedMean(X)*: Returns the mean magnitude from all station magnitudes
differing less than *X* magnitudes from the median.
.. _concepts_magnitudes-moment:
Moment Magnitudes
=================
@ -165,6 +272,8 @@ usually referred to as *M*. The name is configurable.
:term:`origin`.
.. _concepts_magnitudes-preferred:
Preferred Magnitude
===================

16
share/doc/seiscomp/html/_sources/base/concepts/messaging.rst.txt
View File

@ -140,9 +140,11 @@ Examples:
connection.server = localhost/production
On the command line use, e.g. ::
On the command line use, e.g.
$ scolv -H localhost
.. code-block:: sh
scolv -H localhost
* Connect to the production queue of the messaging on localhost with default port.
Using non-default secure encryption and port the scheme and the port must be
@ -150,9 +152,11 @@ Examples:
connection.server = scmps://localhost18181/production
On the command line use, e.g. ::
On the command line use, e.g.
$ scolv -H scmps://localhost:18181/production
.. code-block:: sh
scolv -H scmps://localhost:18181/production
.. _messaging-db :
@ -172,7 +176,9 @@ When connecting from a client to the messaging, the database connection paramete
are reported by :ref:`scmaster`. They can be overridden by the global configuration
or command-line option ``-d``.
Example: ::
Example:
.. code-block:: sh
scolv -H localhost -d mysql://sysop:sysop@localhost/seiscomp-test

155
share/doc/seiscomp/html/_sources/base/contributing-docs.rst.txt
View File

@ -10,18 +10,17 @@ It aims to document the configuration and command line options for
consistent way. The functionality of |scname| differs between
versions so the documentation is versioned along with |scname|.
For more general topics and tutorials please refer to the
`SeisComP wiki`_.
|scname| website and documentation :cite:p:`seiscomp`.
The documentation is written in `reStructuredText`_ (reST) a
simple text mark up format. The documentation is generated using `Sphinx`_
which is used to create the `Python documentation`_.
The Sphinx website has a very good
`introduction to reST`_ and also covers the Sphinx specific
`directives`_.
The documentation is written in :cite:t:`reStructuredText` (reST) a simple text
mark up format. The documentation is generated using Sphinx :cite:p:`sphinx`
which is used to create the Python documentation :cite:p:`python-doc`.
The Sphinx website :cite:p:`reStructuredText-sphinx` has a very good
introduction to reST and also covers the Sphinx-specific
directives :cite:p:`reStructuredText-directives`.
If you would like to add to this documentation or you find an error, then please
submit a patch to `SeisComP on GitHub`_ or report to the
SeisComP `discussion forum`_.
submit a patch to :cite:t:`seiscomp-github` or report to the :cite:t:`seiscomp-forum`.
.. note::
@ -33,54 +32,64 @@ then you can use the *Show Source* link on each page to view the reST
source. The source and the documentation files for executables (see below) are
good starting points for a new patch.
Documenting Executables
=======================
The documentation for executables is generated from two sources:
The documentation for modules and plugins is generated from two sources:
'executable'.xml
An XML file that contains a brief description of the command,
markup describing the command line parameters, and any
configuration parameters for the executable. Each parameter should
An :ref:`XML file <contributing_documentation_XML>` that contains a brief
description of the command, markup describing the command line parameters,
and any configuration parameters for the executable. Each parameter should
have a brief description of the purpose of the parameter.
The description should be plain text and not contain reST markup. Where parameters are common across
a number of executables they should be placed in the appropriate common file and referred to using
their publicID.
The description should be plain text and not contain reST markup. Where
parameters are common across a number of executables they should be placed
in the appropriate common file and referred to using their publicID.
All XML files live in the :file:`doc/apps` directory of the source
distribution or in :file:`etc/descriptions` of an installation.
'executable'.rst
This is a text file in reST markup that gives any more-detailed description and examples for the executable.
It is combined with the corresponding .xml to create the full documentation.
This is a RST text file in :ref:`reST markup <reStructuredText>` that gives
any more-detailed description and examples for modules or plugins. It is
combined with the corresponding :file:`executable.xml` file to create the
full HTML documentation and man pages of a module or plugin.
When listed in a table of content, the RST file allows generating general
content without providing an XML file. Examples can be found in the
`documentation index file`_ .
The first entry in the file should be a paragraph giving a more
detailed description of the executable.
detailed description of the executable. The following paragraphs provide
background information, use cases and examples.
These two files should be placed in a :file:`descriptions` sub-directory of the
respective module, e.g. :file:`src/seedlink/apps/seedlink/descriptions/seedlink.rst`.
The intention is that the documentation is close to the code to make it easier for developers to keep the
documentation up to date with code changes.
respective module or plugin, e.g., the `scolv description`_ .
The intention is that the documentation is close to the code to make it easier
for developers to keep the documentation up to date with code changes.
For a new executable an entry should also be made in the man section of :file:`conf.py`.
The man page is a short form of the documentation that is generated from only the .xml file.
For a new executable an entry can also be made in the man section of
:file:`conf.py`. For |scname| modules located, `documentation templates directory`_.
The man page is a short form of the documentation of a module that is generated
from the XML and the RST files.
Example:
.. code-block:: sh
man scolv
Images
======
Creating the RST
================
Any images should be placed in a suitable sub-directory of :file:`descriptions/media`.
Read the :ref:`documentation on image styles <documentation_style_guide_image>` for more details.
The images can then be referred to (in .rst) like::
The RST file should be written according to the
:ref:`documentation style guide <documentation_style_guide>`.
.. figure:: media/scolv/scolv-overview.png
:width: 16cm
:align: center
Overview of the defrobnicator switches in :ref:`scolv`.
The images will be moved to the correct location during the documentation build.
.. _contributing_documentation_XML:
Understanding the XML
=====================
@ -97,10 +106,13 @@ Any description XML uses the root element *seiscomp*:
...
</seiscomp>
Three elements are used inside the root element: :ref:`module<xml-module>`, :ref:`plugin<xml-plugin>` and :ref:`binding<xml-binding>`.
Modules, plugins and bindings can be described in one XML or split up into one file per description. It is better to
have things as close as possible. A module and its binding should go into one module.XML whereas plugins should
go into separate XML files.
Three elements are used inside the root element: :ref:`module<xml-module>`,
:ref:`plugin<xml-plugin>` and :ref:`binding<xml-binding>`.
Modules, plugins and bindings can be described in one XML or split up into one
file per description. It is better to have things as close as possible. A module
and its binding should go into one module.XML whereas plugins should go into
separate XML files. Examples can be found in the source code as well as in the
XML files installed in :file:`seiscomp/etc/descriptions`.
.. _xml-module:
@ -295,7 +307,6 @@ Element: **configuration**
| | | | |
+-------------------+----------+-----------+---------------------------------------------------+
.. _xml-configuration-parameter:
Element: **parameter**
@ -312,6 +323,13 @@ Element: **parameter**
| | | | configurator to provide specialized input |
| | | | widgets. It is also important for the user |
| | | | how the parameter is read by the module. |
| | | | Supported are: *uint, list:uint, int, list:uint, |
| | | | double, list:double, float, list:float, file, |
| | | | list:file, directory, list:directory, time |
| | | | list:time, host-with-port, boolean, gradient* |
+-------------------+----------+-----------+---------------------------------------------------+
| **options** | attrib | no | Options to type if type is file or directory. |
| | | | Supported: *read, write, execute* |
+-------------------+----------+-----------+---------------------------------------------------+
| **unit** | attrib | no | An optional unit such as "s" or "km" or |
| | | | "deg". |
@ -319,9 +337,28 @@ Element: **parameter**
| **default** | attrib | no | The default value the module uses if this |
| | | | parameter is not configured. |
+-------------------+----------+-----------+---------------------------------------------------+
| **values** | element | no | Lists the supported value separated by comma. For |
| | attrib | | files, the list describes file name suffices. |
+-------------------+----------+-----------+---------------------------------------------------+
| **range** | element | no | The range of values. Format: minimum:maximum |
| | attrib | | |
+-------------------+----------+-----------+---------------------------------------------------+
| **description** | element | no | Gives a brief description of the parameter. |
+-------------------+----------+-----------+---------------------------------------------------+
.. note::
Further explanations of **type**:
* uint: Non-negative integer. Example values: 0, 1
* gradient: Colon-separated pairs of value and color. Example:
-4:"rgb(0,0,255)".
* host-with-port: Colon-separated pairs of host address and port number.
Example: localhost:8080.
* time: Any :ref:`time format supported by SeisComP <time-formats>` is
possible unless stated differently.
* list: One ore more values separated by comma.
.. _xml-configuration-struct:
Element: **struct**
@ -333,6 +370,8 @@ Element: **struct**
| | | | used in a configurator to give a selection |
| | | | of available types to be instantiated. |
+-------------------+----------+-----------+---------------------------------------------------+
| **title** | attrib | no | The title of the struct as shown, e.g. in scconfig|
+-------------------+----------+-----------+---------------------------------------------------+
| **link** | attrib | no | The absolute reference parameter as it would |
| | | | appear in the configuration file which |
| | | | holds all instantiated structures. |
@ -362,8 +401,21 @@ Element: **struct**
| **group** | element | no | Describes a group part of this struct. See |
| | | | :ref:`group<xml-configuration-group>`. |
+-------------------+----------+-----------+---------------------------------------------------+
| **aliases** | attrib | no | Explains where to find alias parameters. |
+-------------------+----------+-----------+---------------------------------------------------+
.. _xml-configuration-extend-struct:
Element: **extend-struct**
+-------------------+----------+-----------+---------------------------------------------------+
| Name | XML type | Mandatory | Description |
+===================+==========+===========+===================================================+
| **type** | attrib | yes | The name of the struct type to be extended. This |
+-------------------+----------+-----------+---------------------------------------------------+
| **match-name** | attrib | no | The name given of the struct with parameters |
| | | | extending name the struct given by name. |
+-------------------+----------+-----------+---------------------------------------------------+
.. _xml-configuration-group:
@ -386,7 +438,6 @@ Element: **group**
| **group** | element | no | Describes a group part of this group. |
+-------------------+----------+-----------+---------------------------------------------------+
Below is an example of the plugin definition for the NonLinLoc plugin. It contains
groups, parameters and structures.
@ -406,7 +457,7 @@ groups, parameters and structures.
</description>
</parameter>
<parameter name="outputPath" type="path" default="/tmp/sc3.nll">
<parameter name="outputPath" type="directory" default="/tmp/sc3.nll">
<description>
Defines the output path for all native NonLinLoc input and
output files.
@ -438,7 +489,6 @@ groups, parameters and structures.
</seiscomp>
.. _xml-command-line:
Command-line
@ -466,7 +516,6 @@ Element: **command-line**
| | | | :ref:`group<xml-command-line-group>`. |
+---------------------+----------+-----------+-----------------------------------------------+
.. _xml-command-line-group:
Element: **group**
@ -484,7 +533,6 @@ Element: **group**
| | | | publicID. |
+---------------------+----------+-----------+-----------------------------------------------+
.. _xml-command-line-option:
Element: **option**
@ -520,7 +568,6 @@ Element: **option**
| **description** | element | no | Gives a brief description of the option. |
+---------------------+----------+-----------+-----------------------------------------------+
Below is an example of the module definition for :program:`scautoloc` (extract).
.. code-block:: xml
@ -533,6 +580,9 @@ Below is an example of the module definition for :program:`scautoloc` (extract).
...
</configuration>
<command-line>
<synopsis>
scautoloc [options]
</synopsis>
<group name="Generic">
<optionReference>generic#help</optionReference>
<optionReference>generic#version</optionReference>
@ -571,11 +621,6 @@ References
.. target-notes::
.. _`SeisComP wiki` : https://www.seiscomp.de/
.. _`reStructuredText` : https://docutils.sourceforge.io/rst.html
.. _`Sphinx` : https://www.sphinx-doc.org/
.. _`Python documentation` : https://docs.python.org/
.. _`introduction to reST` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _`directives` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
.. _`SeisComP on GitHub` : https://github.com/SeisComP
.. _`discussion forum` : https://forum.seiscomp.de
.. _`documentation index file` : https://github.com/SeisComP/seiscomp/blob/master/doc/templates/index.rst
.. _`scolv description` : https://github.com/SeisComP/main/blob/master/apps/gui-qt/scolv/descriptions/
.. _`documentation templates directory` : https://github.com/SeisComP/seiscomp/tree/master/doc/templates

15
share/doc/seiscomp/html/_sources/base/filter-grammar.rst.txt
View File

@ -213,9 +213,9 @@ parentheses, e.g. :py:func:`DIFF()<DIFF()>`, or without, e.g.
.. py:function:: DT
Replaces each input sample with the sampling time of the current sample. This
Replaces each input sample with the sampling interval of the current sample. This
is a shortcut for :code:`1/SR` but more efficient as the division has to be
done only once and not once per input sample.
done only once and not once per input sample. The output unit is *seconds*.
.. py:function:: DURATION(trigger_on, trigger_off)
@ -252,12 +252,14 @@ parentheses, e.g. :py:func:`DIFF()<DIFF()>`, or without, e.g.
:param a: Coefficient `a`.
.. py:function:: ITAPER(timespan)
.. py:function:: ITAPER(timespan[,offset = 0])
A one-sided cosine taper applied when initializing the filter, e.g. at the
beginning of the data or after longer gaps.
:param timespan: The timespan to apply the taper in seconds.
:param timespan: The length of the taper in seconds
:param offset: The offset in counts removed from the data records before
applying the taper. Optional parameter.
.. py:function:: MAX(timespan)
@ -342,7 +344,8 @@ parentheses, e.g. :py:func:`DIFF()<DIFF()>`, or without, e.g.
.. py:function:: SR
Replaces each input sample with the sampling rate of the current sample.
Replaces each input sample with the sampling rate of the current sample. The
output unit is *1/seconds*.
.. py:function:: STALTA(sta, lta)
@ -377,7 +380,7 @@ parentheses, e.g. :py:func:`DIFF()<DIFF()>`, or without, e.g.
Computes the amplitude sum of the timespan preceding the sample.
.. py:function:: WA([type = 1[,gain=2080[,T0=0.8[,h=0.7]]]])
.. py:function:: WA([type = 1[,gain = 2080[,T0 = 0.8[,h = 0.7]]]])
The simulation filter of a :term:`Wood-Anderson seismometer`. The data format
of the waveforms has to be given for applying the simulation filter

135
share/doc/seiscomp/html/_sources/base/getting-started.rst.txt
View File

@ -21,35 +21,10 @@ Once the database server is defined and optimized as described in the section
Initially execute the steps listed in this section. You will need to consider
differences in databases:
* :ref:`MySQL <getting-started-mysql>` (not recommended),
* :ref:`MariaDB <getting-started-mariadb>`,
* :ref:`PostgreSQL <getting-started-postgresql>`.
.. _getting-started-mysql:
MySQL
-----
The initial configuration by the :program:`seiscomp` script or the
wizard of :ref:`scconfig` allows to create and configure the MySQL database
for |scname|. If you want to use MySQL continue with the
:ref:`general setup <getting-started-setup>`.
.. warning ::
* Using MySQL is currently not recommended. Preferably use MariaDB instead of MySQL
as MariaDB is the default SQL flavor of most supported Linux systems!
* As of MySQL 8.0 the password encryption and policy has changed resulting in
errors when connecting to a MySQL server. In 04/2021 this
does not seem to be fully supported in **Ubuntu 20.04**. Therefore, you need
to use a native password on the MySQL server.
.. code-block:: sh
$ sudo mysql -u root -p
ALTER USER 'sysop'@'%%' IDENTIFIED WITH mysql_native_password BY 'my_super_secret_password_matching_the_mysql_password_validation_policy';
* :ref:`PostgreSQL <getting-started-postgresql>`,
* :ref:`SQLite3<getting-started-sqlite3>`,
* :ref:`MySQL <getting-started-mysql>` (not recommended).
.. _getting-started-mariadb:
@ -81,7 +56,7 @@ The full procedure to create the seiscomp database:
.. code-block:: sh
user@host:~$ sudo mysql -u root -p
CREATE DATABASE seiscomp CHARACTER SET utf8mb4;
CREATE DATABASE seiscomp CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
grant usage on seiscomp.* to sysop@localhost identified by 'sysop';
grant all privileges on seiscomp.* to sysop@localhost;
grant usage on seiscomp.* to sysop@'%' identified by 'sysop';
@ -92,11 +67,10 @@ The full procedure to create the seiscomp database:
user@host:~$ mysql -u sysop -p seiscomp < ~/seiscomp/share/db/mysql.sql
.. note::
If character set 'utf8mb4' is not supported by your specific database server
version then use the old 'utf8' format. For historical reasons, SeisComP
would use then the 'utf8_bin' collation. The full statement looks as
follows: :code:`CREATE DATABASE seiscomp CHARACTER SET utf8 COLLATE utf8_bin`.
version then use the old 'utf8' format. The full statement looks as follows:
:code:`CREATE DATABASE seiscomp CHARACTER SET utf8 COLLATE utf8_bin`.
.. _getting-started-postgresql:
@ -108,14 +82,13 @@ for |scname|.
It also allows :ref:`creating the database <database_configuration_postgresql>`
and the database tables.
For a manual setup of the PostgreSQL database first :ref:`setup the database
server<database_configuration_postgresql>`, then create the user, the database
and the tables.
For a manual setup of the PostgreSQL database first
:ref:`setup the database server<database_configuration_postgresql>`. Thereafter
create the user, the database and the tables.
#. Create the user and the database
:program:`CentOS`:
:program:`RHEL`:
.. code-block:: sh
@ -138,7 +111,42 @@ and the tables.
user@host:~$ psql -f ~/seiscomp/share/db/postgres.sql -t seiscomp -U sysop
Continue with the :ref:`general setup <getting-started-setup>` considering the
created database but **do not create the database again**.
created database but you do not need to create the database again.
.. _getting-started-sqlite3:
SQLite3
-------
Alternatively, a SQLite3 database can be used. The setup up is identical to the
other databases and described in section :ref:`getting-started-setup` .
.. _getting-started-mysql:
MySQL
-----
The initial configuration by the :program:`seiscomp` script or the
wizard of :ref:`scconfig` allows to create and configure the MySQL database
for |scname|. If you want to use MySQL continue with the
:ref:`general setup <getting-started-setup>`.
.. warning::
* Using MySQL is currently not recommended. Preferably use MariaDB instead of MySQL
as MariaDB is the default SQL flavor of most supported Linux systems!
* As of MySQL 8.0 the password encryption and policy has changed resulting in
errors when connecting to a MySQL server. In 04/2021 this
does not seem to be fully supported in **Ubuntu 20.04**. Therefore, you need
to use a native password on the MySQL server.
.. code-block:: sh
$ sudo mysql -u root -p
ALTER USER 'sysop'@'%%' IDENTIFIED WITH mysql_native_password BY 'my_super_secret_password_matching_the_mysql_password_validation_policy';
.. _getting-started-setup:
@ -204,20 +212,18 @@ trunk modules and the default request handler of Arclink.
.. code-block:: none
0) mysql
MySQL server.
Enable database storage. [yes]:
0) mysql/mariadb
MySQL/MariaDB server.
1) postgresql
PostgreSQL server. There is currently no support in setup to create the
database for you. You have to setup the database and user accounts on
your own. The database schema is installed under share/db/postgresql.sql.
PostgresSQL server version 9 or later.
2) sqlite3
SQLite3 database.
Database backend [0]:
If the database is enable the database backend can be selected. |scname|
supports two main backends: MySQL and PostgreSQL. Select the backend to be used
here but be prepared that only for the MySQL backend the setup can help to
create the database and tables for you. If you are using PostgreSQL you have
to provide a working database with the correct schema. The schema files are
part of the distribution and can be found in :file:`seiscomp/share/db/postgresql.sql`.
If the database is enabled, the database backend can be selected. |scname|
supports three main backends: MariaDB/MySQL, PostgreSQL, and SQLite3. Select the
backend to be used.
.. note::
@ -236,13 +242,6 @@ part of the distribution and can be found in :file:`seiscomp/share/db/postgresql
Create database [yes]:
.. warning ::
If MySQL is selected it is possible to let :command:`seiscomp setup` to create
the database and all tables for you. Otherwise currently not and you need to set up the
database manually following the :ref:`given instructions <getting-started-mysql>`.
If the database has been created already, answer 'no' here.
----
.. code-block:: none
@ -294,12 +293,16 @@ without doing anything.
Command? [P]:
.. _getting-started-variables:
Environment variables
=====================
Commands can be used along with the :program:`seiscomp` script located in *seiscomp/bin/seiscomp*.
Read the section :ref:`sec-management-commands` for more details on :program:`seiscomp`.
E.g. |scname| modules can be executed like ::
E.g. |scname| modules can be executed like
.. code-block:: sh
user@host:~$ seiscomp/bin/seiscomp exec scrttv
@ -314,11 +317,15 @@ Providing the full path allows starting other |scname| modules in a specific
|scname| environment. Thus, multiple SeisComP installations can be maintained
and referred to on the same machine.
:program:`seiscomp` can also be used for printing the considered |scname| environment ::
:program:`seiscomp` can also be used for printing the considered |scname| environment
.. code-block:: sh
user@host:~$ seiscomp/bin/seiscomp print env
resulting in ::
resulting in
.. code-block:: sh
export SEISCOMP_ROOT="/home/sysop/seiscomp"
export PATH="/home/sysop/seiscomp/bin:$PATH"
@ -335,11 +342,15 @@ executed without the :program:`seiscomp` script.
For setting the environment
#. Use the :program:`seiscomp` script itself to generate the parameters and write
the parameters to :file:`~/.bashrc` ::
the parameters to :file:`~/.bashrc`
.. code-block:: sh
user@host:~$ seiscomp/bin/seiscomp print env >> ~/.bashrc
#. Load the environment or log out and in again ::
#. Load the environment or log out and in again
.. code-block:: sh
user@host:~$ source ~/.bashrc

32
share/doc/seiscomp/html/_sources/base/glossary.rst.txt
View File

@ -343,7 +343,7 @@ Scientific and technical terms
seismicity. It is the main development and service company for |scname|.
GEOFON
GEOFON (https://geofon.gfz-potsdam.de) is part of the Modular Earth Science
GEOFON (https://geofon.gfz.de) is part of the Modular Earth Science
Infrastructure (MESI) at :term:`GFZ`.
geometrical spreading
@ -351,8 +351,8 @@ Scientific and technical terms
increasing distance from a given source.
GFZ
Helmholtz Centre Potsdam `German Research Centre for Geosciences <http://www.gfz-potsdam.de/>`_.
|scname| was originally developed at GFZ.
`GFZ Helmholtz Centre for Geosciences <http://www.gfz.de/>`_. |scname| was
originally developed at GFZ.
GMPE
Ground Motion Prediction Equation
@ -626,21 +626,14 @@ Scientific and technical terms
magnitude, broadband surface wave (Ms(BB))
Ms(BB) is a broadband magnitude scale based on teleseismic surface waves.
In contrast to :term:`Ms <magnitude, surface wave (Ms)>`, amplitudes for Ms(BB)
In contrast to :term:`Ms <magnitude, surface wave (Ms)>`/
:term:`Ms <magnitude, surface wave (Ms_20)>`, amplitudes for Ms(BB)
are measured as the maximum on vertical true ground motion velocity seismograms without
instrument simulation or restitution.
The Moscow-Prague equation for surface wave magnitude is applied as given by
.. math::
M_s = \log \left(\frac{A}{2\pi}\right) + 1.66 \log(\Delta) + 3.3
* Amplitude unit in |scname|: **meter per second** (m/s)
* Period range: all
* Distance range: 2 - 160°
* Depth range: 0 - 100 km
* Time window: distance (km) / 3.5 km/s + 30 s
The Moscow-Prague equation for surface wave magnitude is applied.
Read the :ref:`technical documentation <global_msbb>` for more details and
the configuration.
magnitude, duration (Md)
The duration magnitude measured on the coda wave train.
@ -998,7 +991,7 @@ Scientific and technical terms
:term:`SeisComP` Markup Language. SCML is a flavor of `QuakeML
<https://quake.ethz.ch/quakeml/>`_ and is used by |scname| and by
products of :term:`gempa GmbH` for exchange. For details read the
`UML diagram <https://geofon.gfz-potsdam.de/_uml/>`_.
`UML diagram <https://geofon.gfz.de/_uml/>`_.
SDS
|scname| Data Structure which is used for archiving waveform data. Below the
@ -1026,10 +1019,9 @@ Scientific and technical terms
seismological data acquisition and real-time data exchange over internet.
Its data transmission protocol SeedLink became a de facto world standard.
The first version of SeisComP was developed for the `GEOFON
<http://geofon.gfz-potsdam.de/geofon/>`_ network and further extended
within the MEREDIAN project under the lead of `GEOFON
<http://geofon.gfz-potsdam.de/geofon/>`_/`GFZ
<http://www.gfz-potsdam.de/>`_ Potsdam and `ORFEUS
<http://geofon.gfz.de>`_ network and further extended within the MEREDIAN
project under the lead of `GEOFON <http://geofon.gfz.de>`_/`GFZ
<http://www.gfz.de>`_ Potsdam and `ORFEUS
<http://www.orfeus-eu.org/>`_. Originally SeisComP was designed as a high
standard fully automatic data acquisition and (near-)real-time data
processing tool including quality control, event detection and location as

10
share/doc/seiscomp/html/_sources/base/history.rst.txt
View File

@ -19,7 +19,9 @@ Following the devastating 2004 Indian Ocean earthquake and tsunami, the
to additional functionality being implemented to fulfill the requirements of
24/7 early warning control centers. Major changes in the architecture of SeisComP
were necessary and many new features resulted in the upgrade of SeisComP to
version 3.
version 3, resulting in the new name SeisComP3. Since the major software redesign
including a new messaging system and the switch to AGPL in 2020 the term
SeisComP is exclusively used along with the version number.
Since 2008 SeisComP has been jointly developed by :term:`gempa GmbH`, a spin-off
company of GFZ and GFZ. Nowadays, gempa GmbH is the main SeisComP developing and
@ -51,7 +53,7 @@ are documented in the :ref:`changelog <sc-changelog>`.
| 2.5 | | March 2006 | Integration of add-on packages, modular config |
| | | | script |
+---------+-----------+--------------------+-----------------------------------------------------+
| 3.0 | alpha | May 2007 | new architecture, new magnitude types, GUI |
| 3.0 | alpha | May 2007 | New architecture, new magnitude types, GUI |
+---------+-----------+--------------------+-----------------------------------------------------+
| 3.0 | Barcelona | May 2008 | Stability and performance improvements, improved |
| | | | GUI functionality |
@ -69,3 +71,7 @@ are documented in the :ref:`changelog <sc-changelog>`.
| 4.0.0 | | May 2020 | Adopts the GNU Affero General Public License v. 3.0,|
| | | | (AGPL), support for Python3 and QT5 |
+---------+-----------+--------------------+-----------------------------------------------------+
| 5.0.0 | | June 2022 | |
+---------+-----------+--------------------+-----------------------------------------------------+
| 6.0.0 | | November 2023 | |
+---------+-----------+--------------------+-----------------------------------------------------+

258
share/doc/seiscomp/html/_sources/base/installation.rst.txt
View File

@ -10,10 +10,12 @@ long-term support (LTS). The Linux flavors under which |scname| has been tested
are given along with the |scname| package names on the download sites of
:cite:t:`seiscomp` and :cite:t:`gempa`.
The software can be obtained and installed from
|scname| can be obtained and installed from
* Officially released packages (TAR files) for different release versions,
Linux systems and architectures,
* Officially released packages (TAR files) for different
:ref:`release versions <installation_versions>`, Linux systems and
architectures from the download sites of |scname| :cite:p:`seiscomp` or from
:cite:t:`gempa-download`.,
* :ref:`Source code available on GitHub <build>`.
Packages may include
@ -30,10 +32,90 @@ Download these packages from :cite:t:`seiscomp` or :cite:t:`gempa-download`.
The next sections describe the installation of the binary packages of |scname|
on
* :program:`Ubuntu 18`, 64 bit system,
* :program:`CentOS 7`, 64 bit system.
* :program:`Ubuntu`, 64 bit system,
* :program:`RHEL`, 64 bit system.
.. _installation_versions:
SeisComP Versions
=================
|scname| has :ref:`developed over time <history>`. The versions can be
distinguished by the name of the release:
* **SeisComP since version 4.0.0** uses release version numbers such as *5.2.1*
where
* 5: major version with changes in API and database schema version, new features,
bug fixed, optimizations,
* 2: minor version with new features, bug fixed, optimizations,
* 1: patch number with bug fixes, optimizations.
* **SeisComP3** uses release versions, names, numbers and patch numbers.
Full example: *SeisComP3-jakarta-2020.330.02*
* 3: release version
* jakarta: release name
* 2020.330: release number
* 02: patch number
Names are adjusted depending on changes in source code:
* **Release version:** major changes in module groups, functionality,
concepts, data model.
Example: SeisComp3 is SeisComP in version 3.0
in comparison to version 2.5 the GUIs were introduced.
* **Release name:** major changes in functionality, concepts, data model.
Example: with SeisComP3-Seattle the new user friendly configuration GUI
:ref:`scconfig` was introduced.
* **Release number:** changes in data model version and/or major changes in
applications and optimizations.
The numbers include the year and the day of the year of the software
release. Example: Jakarta-2018.327
* **Patch number:** optimizations of applications without changes in the data
model version.
The version number of the installed |scname| can be obtained by
* This documentation where it printed in the header along with the SeisComP icon
* The running any |scname| module on the command-line using :option:`-V` such as
.. code-block:: sh
$ scm -V
scm
Framework: 6.8.4 Release
API version: 16.3.0
Data schema version: 0.13
GIT HEAD: c28f6323
Compiler: c++ (Ubuntu 13.2.0-23ubuntu4) 13.2.0
Build system: Linux 6.8.12-11-pve
OS: Ubuntu 24.04 LTS / Linux
.. _installation-os:
Supported Operating Systems
===========================
|scname| is developed and tested on Linux for the latest stable flavors with
long-term support (LTS) and on x86_64 architecture. For |scname| in version
7.*.*. the minimum OS and version are
* Debian: 11
* RHEL: 8
* Ubuntu: 22.04
Higher versions of |scname| will require higher OS versions.
Packages for more flavors and versions may be found on
`the SeisComP website <https://www.seiscomp.de/downloader/>`_.
.. _installation-hw:
Hardware Requirements
=====================
@ -50,7 +132,6 @@ Minimum requirements are:
CPU; 2
RAM; 4 GB
HDD; 20 GB
OS; Ubuntu last 3 major LTS versions, 64bit, Debian 8.0 64bit, RHEL 7, CentOS 7 64bit
In case large networks (>100 stations) are operated, a distributed system is
recommended. Normally a |scname| system is separated in several subsystems.
@ -93,17 +174,58 @@ GUI system:
.. _installation-packages:
Installation from Packages
==========================
Installation of Packages
========================
This section describes the installation of |scname| from compiled |scname|
packages which ship as :file:`*.tar.gz` files.
This section describes the initial installation of |scname| from compiled
|scname| packages which ship as :file:`*.tar.gz` files. For installation from
source code follow the instructions outlined in section :ref:`compiling_source`.
You may install the |scname| packages in either way:
* :ref:`gsm<installation-gsm>` (recommended) a package manager provided by
:cite:t:`gempa`,
* :ref:`manually by extracting packages <installation-manual>`.
For later updates/upgrades read the tutorial :ref:`tutorials_upgrade`.
.. hint::
We recommend to track any changes in the installation and configuration of
|scname| except :file:`seiscomp/var`, :file:`seiscomp/share/maps` and large
binary files or files changing often during |scname| operation
(e.g. :ref:`global_hypo71`, :ref:`global_nonlinloc` input and output files)
using :program:`git`.
.. _installation-gsm:
gsm
---
Installation of packages by gsm :cite:p:`gsm` is
recommended allowing to easily update/upgrade or add/remove packages in the
future and in order to maintain a clean file structure also after
updates/upgrades. If you wish to install and maintain |scname|
by :program:`gsm` :cite:p:`gsm`, then read the instruction given in the
:cite:t:`gsm-doc`.
.. note::
While :program:`gsm` :cite:p:`gsm` allows the installation of software
packages the OpenSource map package of |scname| must be
:ref:`installed manually <installation-manual>`.
Steps to take
-------------
.. _installation-manual:
Simply follow a few steps to complete your installation of |scname|:
Manual unpacking
----------------
A simply installation can be done by simply downloading and unpacking the
packages, but installation and maintenance using :ref:`gsm<installation-gsm>`
is recommended.
For simple unpacking follow a few steps to complete your installation of
|scname|:
#. Log in to your Linux system as user, e.g. sysop, the standard user in this
documentation.
@ -150,16 +272,18 @@ Simply follow a few steps to complete your installation of |scname|:
user@host:~$ tar xzf seiscomp-[version]-doc.tar.gz
Unpacking these files creates the |scname| :ref:`directory structure<directory_structure>`.
.. _directory_structure:
Directory structure
-------------------
Directory Structure
===================
All installed files and directories are found below the *seiscomp* directory.
The directory structure of the installed system is described the table below.
The installation of |scname| creates the |scname|
:ref:`directory structure<directory_structure>`.
All installed files and directories are found below the *seiscomp* directory
unless an alternative directory is given when installing with :program:`gsm` or
:ref:`compiling from source code<compiling_source>`.
The directory structure of the installed system is described in the table below.
.. csv-table::
:widths: 10 90
@ -188,76 +312,63 @@ The directory structure of the installed system is described the table below.
.. _software_dependencies:
Software dependencies
---------------------
Software Dependencies
=====================
|scname| depends on a number of additional software packages shipped with each
Linux distribution.
After installation of |scname| these packages can be installed using the
:program:`seiscomp`.
The :program:`seiscomp` tool comes with
the command :command:`install-deps` which installs required packages.
Read the section :ref:`System management<system-management>` for more detailed
instructions. For example, to install the dependencies for using the MariaDB
database, give 'mariadb-server' as parameter.
:ref:`seiscomp` script.
:ref:`seiscomp` comes with the command :command:`install-deps` which installs
required packages. For example, to install the dependencies for
using the MariaDB database, give 'mariadb-server' as parameter.
.. code-block:: sh
user@host:~$ seiscomp/bin/seiscomp install-deps base mariadb-server
Distribution: Ubuntu 18.04
Distribution: Ubuntu 24.04
[sudo] password for sysop:
Reading package lists... Done
Building dependency tree
Reading state information... Done
...
More options for systems with GUIs and FDSNWS are: ::
user@host:~$ seiscomp/bin/seiscomp install-deps gui fdsnws
If your distribution is not supported by :command:`install-deps`,
install the above packages manually:
:program:`Ubuntu` `version`
More requirements for systems with GUIs, FDSNWS and iLoc are:
.. code-block:: sh
user@host:~$ cd seiscomp/share/deps/ubuntu/[version]
...
user@host:~$ seiscomp/bin/seiscomp install-deps gui
user@host:~$ seiscomp/bin/seiscomp install-deps fdsnws
user@host:~$ seiscomp/bin/seiscomp install-deps iloc
:program:`CentOS` `version`
If your distribution is not supported by :ref:`seiscomp` *install-deps*,
install the above packages manually from the scripts within the OS- and
version-dependent directories:
.. code-block:: sh
user@host:~$ cd seiscomp/share/deps/centos/[version]
user@host:~$ cd seiscomp/share/deps/[OS]/[version]
...
.. code-block:: sh
su root
bash install-mariadb-server.sh
bash install-postgresql-server.sh
bash install-base.sh
bash install-gui.sh
bash install-fdsnws.sh
...
or contact the |scname| developers to add support for your distribution.
Read the section :ref:`System management<system-management>` for more detailed
options and instructions.
.. warning::
Either the MariaDB **or** the MySQL server can be installed; not both at the
same time. When replacing on by the other, ensure that all related files are
Either the MariaDB **or** the MySQL server can be installed; **not both at the
same time**. When replacing one by the other, ensure that all related files are
removed before installing the alternative server. For MySQL instead of MariaDB
use: ::
use:
.. code-block:: sh
root@host:~$ sh install-mysql-server.sh
Preferably use MariaDB instead of MySQL as MariaDB is the default for the
supported Linux distributions!
.. note ::
.. note::
Linux systems develop dynamically and the installation of the dependencies
may be incomplete. |scname| modules will stop and indicate the missing software.
@ -304,7 +415,7 @@ MariaDB / MySQL
innodb_buffer_pool_size = <your value>
innodb_flush_log_at_trx_commit = 2
.. note ::
.. note::
The location of the configuration file can differ between distributions.
@ -312,7 +423,7 @@ MariaDB / MySQL
:file:`/etc/mysql/mariadb.conf.d/50-server.cnf`
:program:`CentOS`:
:program:`RHEL`:
:file:`/etc/my.cnf`
@ -327,7 +438,7 @@ MariaDB / MySQL
user@host:~$ sudo systemctl enable mariadb
:program:`CentOS`
:program:`RHEL`
.. code-block:: sh
@ -337,11 +448,15 @@ MariaDB / MySQL
* If you make a fresh installation of MariaDB/MySQL, secure the database and set
a password for the root user
:program:`Ubuntu` ::
:program:`Ubuntu`
.. code-block:: sh
user@host:~$ sudo mysql_secure_installation
:program:`CentOS` ::
:program:`RHEL`
.. code-block:: sh
user@host:~$ su root
root@host:~$ mysql_secure_installation
@ -361,14 +476,14 @@ MariaDB / MySQL
user@host:~$ sudo systemctl restart mariadb
:program:`CentOS`:
:program:`RHEL`:
.. code-block:: sh
user@host:~$ su root
root@host:~$ systemctl restart mariadb
.. note ::
.. note::
Replace mariadb by mysql when using MySQL instead of MariaDB.
@ -385,15 +500,14 @@ PostgreSQL
after |scname| database initialization. Here an example how to enable
user/password authentication for local and remote connections.
.. code-block:: sh
# TYPE DATABASE USER ADDRESS METHOD
# IPv4 local connections:
host seiscomp sysop 0.0.0.0/0 md5
host all all 127.0.0.1/32 ident
# TYPE DATABASE USER ADDRESS METHOD
# IPv4 local connections:
host seiscomp sysop 0.0.0.0/0 md5
host all all 127.0.0.1/32 ident
.. note ::
.. note::
The order of the rules matters and the location of the configuration file
can differ between distributions.
@ -402,7 +516,7 @@ PostgreSQL
:file:`/etc/postgresql/10/main/pg_hba.conf`
:program:`CentOS`:
:program:`RHEL`:
:file:`/var/lib/pgsql/data/pg_hba.conf`
@ -414,7 +528,7 @@ PostgreSQL
listen_addresses = 0.0.0.0/0
.. note ::
.. note::
The location of the configuration file can differ between distributions.
@ -422,7 +536,7 @@ PostgreSQL
:file:`/etc/postgresql/10/main/postgresql.conf`
:program:`CentOS`:
:program:`RHEL`:
:file:`/var/lib/pgsql/data/postgresql.conf`

27
share/doc/seiscomp/html/_sources/base/management.rst.txt
View File

@ -86,10 +86,23 @@ The *seiscomp* script can be executed with additional commands:
* **install-deps** [packages]
Installs 3rd party packages on which |scname| depends such as MariaDB or MySQL.
Installs 3rd-party packages on which |scname| depends such as MariaDB or MySQL.
This is currently only supported for major Linux distributions. A list of packages
needs to be given. Available packages are: **base**, **GUI**,
**mariadb-server**, **postgresql-server**, **fdsnws**.
needs to be given. Available packages are defined in BASH scripts located in
:file:`@DATADIR@/deps/[os]/[version]/install-[name].sh`:
.. csv-table::
:widths: 40 60
:align: left
:delim: ;
:header: Package name, Installation
base; Base libraries needed for all |scname| module
gui; Libraries for running graphical interfaces
mariadb-server/mysql-sever; Mariadb/MySQL server
postgresql-server; Postgresql server
fdsnws; Python modules for running FDSNWS
iloc; Auxiliary files for :ref:`global_iloc` from :cite:t:`iloc-github`
#. Install only base system dependencies:
@ -117,6 +130,12 @@ The *seiscomp* script can be executed with additional commands:
seiscomp install-deps gui fdsnws
#. For using :ref:`global_iloc`:
.. code-block:: sh
seiscomp install-deps iloc
* **list** modules|aliases|enabled|disabled
Lists items.
@ -237,7 +256,7 @@ Examples
/home/sysop/seiscomp/etc/key/seedlink/profile_geofon
--------------------------------------------------------------------------------
sources = chain
sources.chain.address = geofon.gfz-potsdam.de
sources.chain.address = geofon.gfz.de
sources.chain.port = 18000
--------------------------------------------------------------------------------

5
share/doc/seiscomp/html/_sources/base/overview.rst.txt
View File

@ -126,8 +126,9 @@ Here *alphanumeric* means the digits 0 to 9, and uppercase letters A-Z.
For publicly-available seismic stations these are typically supplied
by external servers such as :ref:`seedlink` or :cite:t:`caps` servers.
For example, the :cite:t:`geofon` seismic network makes data available at port 18000
at geofon.gfz-potsdam.de which you may query and test using :ref:`slinktool`.
For example, the :cite:t:`geofon` seismic network makes data available at port
*18000* at *geofon.gfz.de* which you may query and test using
:ref:`slinktool`.
If you operate your own seismic network, you may collect data directly
from your station's digitizer using one of the many plugins included with

230
share/doc/seiscomp/html/_sources/base/style-guide.rst.txt
View File

@ -8,19 +8,23 @@ Style Guide for Documentation
File Layout
===========
The documentation of an executable module comes as a pair of source files:
The documentation of an executable module or plugin comes as a pair of source
files:
* A description XML file (.xml) giving command details, command-line and configuration parameters,
* A documentation reST text file (.rst) gives a more-detailed module description and examples.
* A :ref:`description XML file (.xml) <contributing_documentation_XML>` giving
command details, command-line and configuration parameters,
* A :ref:`documentation reST text file (.rst) <documentation_style_guide_rst>`
gives a more-detailed module description and examples.
Any other documentation, e.g. this style guide, tutorials, etc. only require the
documentation reST text file.
The reST text file should follow the guidelines in this style guide.
The :ref:`contributing_documentation` section details the documentation
requirements for executables including the structure of description XML files.
The :ref:`contributing_documentation` section details
the documentation requirements for executables including the structure of description XML files.
.. _documentation_style_guide_rst:
Documentation Syntax
====================
@ -35,10 +39,10 @@ Add information about testing and examples into their own sections.
General principles
------------------
- If possible, keep line lengths under 80 characters.
- It eases later editing if sentences in the raw RST start on a new
* If possible, confine lines to 80 characters.
* It eases later editing if sentences in the raw RST start on a new
line, even though they will flow together in the finished document.
- It is helpful if long text objects such as HTML link text each
* It is helpful if long text objects such as HTML link text each
appear on their own line.
@ -53,14 +57,14 @@ description information in the appropriate part of the documentation.
While RST doesn't care too much about what syntax is used for
headings, it is best to stick to one style consistently.
Thus, you will generally need only two levels of headings but you can add more.
Thus, you will generally need only few levels of headings but you can add more.
+-------+------------------------------+
| Level | Mark up beneath heading text |
+=======+==============================+
| 1 | ' ==== ' |
+-------+------------------------------+
| 2 | " ---- " |
| 2 | ' - - - ' |
+-------+------------------------------+
| 3 | ' ~~~~ ' |
+-------+------------------------------+
@ -89,8 +93,9 @@ Parts such as Examples are marked in **bold**.
However notes and figures should use the appropriate RST directive, and don't require their own headings.
- One blank line below headings is enough.
- Two lines above are often used, and this looks better than one.
* One blank line below headings is enough.
* Two lines above are often used, and this looks better than one.
Lists
-----
@ -122,10 +127,44 @@ Use numbered or unnumbered lists at several levels.
* subitem 2.
Other markup tools and conventions
----------------------------------
Tables
------
- **Code fragments:** Use the reST code-block syntax for code fragments, with
Tables may be generated as CSV tables defining the
* column width
* header text
* alignment
* delimiter
* table content
.. code-block:: rst
.. csv-table::
:widths: 20 80
:header: Item, Value
:align: center
:delim: ;
1; value for item 1
2; value for item 2
**Result:**
.. csv-table::
:widths: 20 80
:header: Item, Value
:align: center
:delim: ;
1; value for item 1
2; value for item 2
Other tools and conventions
---------------------------
* **Code fragments:** Use the reST code-block syntax for code fragments, with
flavors like "c", "python", "sh", "bash", "properties´" or "xml" as appropriate:
.. code-block:: rst
@ -142,7 +181,7 @@ Other markup tools and conventions
#!/bin/bash
echo $SEISCOMP_ROOT
- **Configuration parameters:** Configuration values have a special
* **Configuration parameters:** Configuration values have a special
syntax. Use the ':confval:' indicator for referencing a module configuration
parameter:
@ -150,20 +189,24 @@ Other markup tools and conventions
:confval:`logging.level`
Result: :confval:`logging.level`.
Using this tag allows a link to be made within the documentation of that module
to the given configuration of the same module. The parameter must be defined
in the description XML file of the module.
- **Command-line options:** Command-line options have a special
* **Command-line options:** Command-line options have a special
syntax. Use the ':option:' indicator for referencing an option:
.. code-block:: rst
:option:`--help`
The option must be defined in the description XML file of the module.
Result: :option:`--help`.
- **Configuration files:** Use the reST ':file:' indicator to refer to files such
The option must be defined in the description XML file of the module or global.
* **Configuration files:** Use the reST ':file:' indicator to refer to files such
as configuration files:
.. code-block:: rst
@ -172,7 +215,7 @@ Other markup tools and conventions
Result: :file:`$SEISCOMP_ROOT/etc/scautopick.cfg`
- **Programs:** Use the reST ':program:' indicator for |scname| programs:
* **Programs:** Use the reST ':program:' indicator for |scname| programs:
.. code-block:: rst
@ -180,7 +223,7 @@ Other markup tools and conventions
Result: :program:`scautopick`
- **References:** Use the reST ':ref:' indicator for cross referencing |scname|
* **References:** Use the reST ':ref:' indicator for cross referencing |scname|
module documentation pages:
.. code-block:: rst
@ -189,7 +232,7 @@ Other markup tools and conventions
Result: :ref:`scautopick`
- **Glossary:** Use the reST ':term:' indicator for referencing terms in the
* **Glossary:** Use the reST ':term:' indicator for referencing terms in the
|scname| :ref:`glossary`:
.. code-block:: rst
@ -198,6 +241,27 @@ Other markup tools and conventions
Result: :term:`magnitude`
* **Download link:** Use the reST ':download:' indicator for referencing a file
in the local file system. The file is loaded when clicking on the link
.. code-block:: rst
:download:`changelog <./CHANGELOG.md>`
Result: :download:`changelog <./CHANGELOG.md>`
.. hint::
When using the reST indicators, text may be given which is shown instead of
the actual link. Enclose the actual link within '<link>' and prepend the
actual text. Example
.. code-block:: rst
:ref:`the scautopick module <scautopick>`
Result: :ref:`the scautopick module <scautopick>`
.. _documentation_style_guide_links:
@ -208,19 +272,19 @@ Create links to sections and subsections within and to figures the text which c
Use unique link names, e.g. including the upper-level section name or the module name.
Use appropriate short names to fit within the texts.
Link within this documentation to the section on headings:
Create a label within this |scname| documentation to the section on headings:
.. code-block:: rst
.. _documentation_style_guide_headings:
Reference:
and refer to the lable within the text:
.. code-block:: rst
:ref:`short name <documentation_style_guide_headings>`
:ref:`link to this section <documentation_style_guide_headings>`
Result: :ref:`short name <documentation_style_guide_headings>`
Result: :ref:`link to this section <documentation_style_guide_headings>`
External links and references
@ -336,66 +400,19 @@ Make sensible use of it!
This adds an important warning.
English Language
================
- SeisComP (capital P), not SeisComP 3 or SC3.
- |scname| module names are proper nouns, even though written with lower case.
Thus they do not need an article.
* Correct: "Although :program:`scmaster` receives a message"
* Incorrect: "Although the scmaster receives a message..."
A sentence may begin with a lower case module name e.g. "scmaster has five modes..."
avoiding this: "The :program:`scmaster` module has..."
- Word separation:
- Separate words:
base class, wave number, time span
- One word:
aftershock, foreshock, *and mainshock too*,
bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform
- Difficult:
high-pass filter; command line; command-line parameter
- Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
See the `discussion`_, e.g.:
- Use command-line parameters
- Type on the command line
- Spelling:
Use American English:
- With 'z': digitizer, realize, visualize, synchronize, behavior, color.
- With 's': license.
- Center, data center.
- Case:
- SEED, miniSEED (miniSEED in :cite:t:`libmseed-github`, or MiniSEED,
but Mini-SEED appears in Appendix G of the :cite:t:`seed-2012`.)
- Ctrl+S for 'control' key plus 's'.
- MySQL, PostgreSQL, MariaDB
- Abbreviations:
- e.g., i.e.
- STA, LTA, STA/LTA detector
- TAR file
.. _documentation_style_guide_images:
Adding Images
=============
Images
------
Code implementation
-------------------
~~~~~~~~~~~~~~~~~~~
The images will be moved to the correct location during the documentation build.
* Place image files in a suitable sub-directory of :file:`descriptions/media`.
* Add images with fixed width.
* Define image alignment.
* Add image captions.
* Store images in a separate directory of below the directory where the
documentation is kept.
@ -436,7 +453,7 @@ Compare with the :ref:`concept section on configuration<concepts_configuration-c
Image style and format
----------------------
~~~~~~~~~~~~~~~~~~~~~~
* Images shall be informative.
* Images must not have any offensive or inappropriate content.
@ -451,6 +468,57 @@ Image style and format
X-forwarding may distort the application features.
English Language
================
* SeisComP (capital P), not SeisComP 3 or SC3.
* |scname| module names are proper nouns, even though written with lower case.
Thus they do not need an article.
* Correct: "Although :program:`scmaster` receives a message"
* Incorrect: "Although the scmaster receives a message..."
A sentence may begin with a lower case module name e.g. "scmaster has five modes..."
avoiding this: "The :program:`scmaster` module has..."
* Word separation:
* Separate words:
base class, wave number, time span
* One word:
aftershock, foreshock, *and mainshock too*,
bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform
* Difficult:
high-pass filter; command line; command-line parameter
* Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
See the `discussion`_, e.g.:
* Use command-line parameters
* Type on the command line
* Spelling:
Use American English:
* With 'z': digitizer, realize, visualize, synchronize, behavior, color.
* With 's': license.
* Center, data center.
* Case:
* SEED, miniSEED (miniSEED in :cite:t:`libmseed-github`, or MiniSEED,
but Mini-SEED appears in Appendix G of the :cite:t:`seed-2012`.)
* Ctrl+S for 'control' key plus 's'.
* MySQL, PostgreSQL, MariaDB
* Abbreviations:
* e.g., i.e.
* STA, LTA, STA/LTA detector
* TAR file
References
==========

19
share/doc/seiscomp/html/_sources/base/tests.rst.txt
View File

@ -7,12 +7,12 @@ Unit Testing
Introduction
============
From Wikipedia:
From Wikipedia [#WPUT]_: ::
In computer programming, unit testing is a software testing method by which
individual units of source code, sets of one or more computer program modules
together with associated control data, usage procedures, and operating
procedures, are tested to determine whether they are fit for use. [#WPUT]_
In computer programming, unit testing is a software testing method by which
individual units of source code, sets of one or more computer program modules
together with associated control data, usage procedures, and operating
procedures, are tested to determine whether they are fit for use.
This chapter targets programmers, either ones contributing to |scname| or
adding their extended set of modules / libraries.
@ -35,6 +35,7 @@ library.
Apart from the availability of the Boost test libraries, cmake with version
2.8.0 or greater is also required.
Preparations
============
@ -53,6 +54,7 @@ its executable against the library the tests are built for.
The recommend test file naming is :code:`{class}_{function}.cpp`.
Execution
=========
@ -62,9 +64,10 @@ Compiling and running tests is as easy as running
make test
in the build directory. Thats it.
in the build directory. That's it.
Test implementation
Test Implementation
===================
The following section shows an example of a simple but in many cases sufficient
@ -108,6 +111,7 @@ your test executable against :code:`${Boost_unit_test_framework_LIBRARY}` and
COMMAND test_mylib_myfeature
)
Warning levels
--------------
@ -163,6 +167,7 @@ Tools
For more tools and information about the Boost unit test tools see [#b4]_.
Test output
===========

87
share/doc/seiscomp/html/_sources/base/time-grammar.rst.txt
View File

@ -13,11 +13,18 @@ Historically, the only time format native to |scname| would be
.. code-block:: properties
YYYY-MM-DD hh:mm:ss.ssssss
'%F %T.%f'
As a consequence of the space between *DD* and *hh* this time string needs
to be enclosed by quotes or double quotes. Otherwise, the time string meant to
be a single string only would be interpreted as two strings. Example:
like
.. code-block:: properties
'2025-01-01 00:00:00.000000'
As a consequence of the space character between *DD* and *HH* this time string
needs to be enclosed by quotes or double quotes. Otherwise, the time string
meant to be a single string only would be interpreted as two strings. Example
application:
.. code-block:: sh
@ -55,55 +62,43 @@ Currently unsupported are:
* Time zone offset designators,
* Local times.
.. csv-table:: List and examples of supported time string formats
:widths: 30 30 40
:header: Implementation, Time string format, Examples: all actual times are identical
.. csv-table:: Table: List and examples of supported time string formats
:widths: 40 60
:header: Implementation (+), Examples: all given times are identical
:align: left
:delim: ;
%FT%T.%fZ ; YYYY-MM-DDThh:mm:ss.ssssssZ ; 2025-01-01T00:00:00.000000Z
%FT%T.%f ; YYYY-MM-DDThh:mm:ss.ssssss ; 2025-01-01T00:00:00.000000
%FT%TZ ; YYYY-MM-DDThh:mm:ssZ ; 2025-01-01T00:00:00Z
%FT%T ; YYYY-MM-DDThh:mm:ss ; 2025-01-01T00:00:00
%FT%R ; YYYY-MM-DDThh:mm ; 2025-01-01T00:00
%FT%H ; YYYY-MM-DDThh ; 2025-01-01T00
%Y-%jT%T.%f ; YYYY-DDDThh:mm:ss.ssssss ; 2025-001T00:00:00.000000
%Y-%jT%T ; YYYY-DDDThh:mm:ss ; 2025-001T00:00:00
%Y-%jT%R ; YYYY-DDDThh:mm ; 2025-001T00:00
%Y-%jT%H ; YYYY-DDDThh ; 2025-001T00
%F %T.%f (*) ; YYYY-MM-DD hh:mm:ss.ssssss ; '2025-01-01 00:00:00.000000'
%F %T (*) ; YYYY-MM-DD hh:mm:ss ; '2025-01-01 00:00:00'
%F %R (*) ; YYYY-MM-DD hh:mm ; '2025-01-01 00:00'
%F %H (*) ; YYYY-MM-DD hh ; '2025-01-01 00'
%F ; YYYY-MM-DD ; 2025-01-01
%Y-%j ; YYYY-DDD ; 2025-001
%Y ; YYYY ; 2025
%FT%T.%fZ ; 2025-01-01T00:00:00.000000Z
%FT%T.%f ; 2025-01-01T00:00:00.000000
%FT%TZ ; 2025-01-01T00:00:00Z
%FT%T ; 2025-01-01T00:00:00
%FT%R ; 2025-01-01T00:00
%FT%H ; 2025-01-01T00
%Y-%jT%T.%f ; 2025-001T00:00:00.000000
%Y-%jT%T ; 2025-001T00:00:00
%Y-%jT%R ; 2025-001T00:00
%Y-%jT%H ; 2025-001T00
%F %T.%f (*) ; '2025-01-01 00:00:00.000000'
%F %T (*) ; '2025-01-01 00:00:00'
%F %R (*) ; '2025-01-01 00:00'
%F %H (*) ; '2025-01-01 00'
%F ; 2025-01-01
%Y-%j ; 2025-001
%Y ; 2025
(+): Compare the formats with those of the :program:`date` command:
:program:`man date`.
(*): Time strings with spaces must be enclosed by quotes or double quotes for
protecting the space.
protecting the space character.
.. csv-table:: List of format symbols used in table of time string formats
:widths: 10 90
:header: Symbol, Description
:align: left
:delim: ;
YYYY; 4-digit year
MM; 2-digit month starting with 01
DD; 1- or 2-digit day of the month starting with 01
DDD; 1-, 2- or 3-digit day of year starting with 001
hh; 1- or 2-digit hour of the day starting with 00
mm; 1- or 2-digit minute of the hour starting with 00
ss; 1- or 2-digit second of the minute starting with 00
ssssss; 1-6 digits decimal fraction of a second with 0
Z; Zone designator for the zero UTC offset
Durations can be formed from start and end dates and times combined by tilde(~).
Example:
Time spans can be formed from start and end dates and times combined by tilde
(~). Examples:
.. code-block:: sh
scart -dsEv -t 2024-01-01T12~2024-01-01T12:15:30.2Z
scart -dsEv -t '2024-01-01 12:00:00~2024-01-01 12:15:30.2'
.. _time-grammar:
@ -258,7 +253,7 @@ Functions
.. py:function:: tt(phase)
Calculates the travel-time of the given phase **w.r.t. relative origin
time, :py:envvar:`OT`**. The result is unset if the travel time cannot be
time**, :py:envvar:`OT`. The result is unset if the travel time cannot be
computed. The travel times are computed based on the travel-time interface
and model defined in :confval:`amplitudes.ttt.interface` and
:confval:`amplitudes.ttt.model`, respectively.
@ -276,9 +271,9 @@ Functions
sensor location of the associated pick must match the sensor
location of the target object.
:param acceptAll: Whether to accept all arrivals or only manually
revised arrivals. The default is 'true' if not
revised arrivals. The default is 'false' if not
given. Allowed is either 'true' or 'false'. If
'true' is given, then either the evaluation mode
'false' is given, then either the evaluation mode
of the origin or the evaluation mode of the pick
must be 'manual'.

2
share/doc/seiscomp/html/_sources/base/tutorials.rst.txt
View File

@ -22,7 +22,7 @@ For details, see the other chapters of this manual.
/base/tutorials/processing
/base/tutorials/geofon_waveforms
/base/tutorials/servefdsnws
/base/tutorials/magnitude-regionalization
/base/tutorials/amplitudes-magnitudes
/base/tutorials/waveformplayback
/base/tutorials/help

528
share/doc/seiscomp/html/_sources/base/tutorials/amplitudes-magnitudes.rst.txt Normal file
View File

@ -0,0 +1,528 @@
.. _tutorials_magnitude-region-aliases:
***************************************************
Amplitudes/Magnitudes: Regionalization, Aliases, Mw
***************************************************
You will ...
* Regionalize magnitudes.
* Create new amplitude and magnitude types as aliases from other amplitudes and
magnitudes.
* Map magnitudes to the moment magnitude, Mw.
:Pre-requisites for this tutorial:
* Read the :ref:`concepts section on magnitudes <concepts_magnitudes>`.
* Real-time data for the station must be available locally.
See :ref:`tutorials_waveforms` or :ref:`tutorials_geofon_waveforms`.
* Inventory must be loaded locally.
:Afterwards/Results/Outcomes:
* Regionalized amplitudes and magnitudes
* New amplitude and magnitude types as aliases
* Moment magnitudes
:Time range estimate:
* 60 minutes
-----------
Regionalization
===============
By regionalization, amplitudes and magnitudes can be computed depending on the
region of the source or source-receiver pairs.
Regions are defined by polygons in BNA or GeoJSON files which must be known to
|scname|.
.. _tutorials_amplitudes-region:
Amplitudes
----------
Measuring amplitudes only for sources or pairs of sources and stations in
specific regions is possible by regionalization. The region polygons are defined
by :ref:`magnitude regionalization <tutorials_magnitude-region>`. In
order to use the feature, regionalized amplitudes and magnitudes must have the
same type (name) and regionalization must be activated per amplitude type in
amplitude-type profiles of global bindings.
.. _tutorials_magnitude-region:
Magnitudes
----------
With regionalization magnitudes can be computed with region-dependent parameters.
If magnitude regionalization is configured but a source or source-station pairs
are not considered, no magnitude of the corresponding type is computed.
Setup
~~~~~
The procedure to set up magnitude regionalization is:
#. Create one file which contains the polygons surrounding the regions within
which magnitude parameters shall apply. The polygon files are provided in
:ref:`BNA <sec-gui_layers-vector-format-bna>` or
:ref:`GeoJSON format <sec-gui_layers-vector-format-geojson>` and located as
set out in the :ref:`documentation of map layers <sec-gui_layers>`. The file
can be created from any |scname| GUI application providing maps, e.g.,
:ref:`scmv`.
#. For the desired magnitude type create a magnitude-type profile in global
module configuration. The name of the profile matches the name of the
magnitude, e.g., *MLc* for the :ref:`MLc magnitude <global_mlc>`.
#. Configure the :confval:`magnitudes.MLc.regionFile` parameter with the full
path and name of the polygon file created above.
#. Within the magnitude-type profile create one or more magnitude-region
profile(s) for defining the regionalized parameters applied to the region(s).
The name of a profile corresponds to the name of the polygon contained in the
polygon file to which the parameters shall apply. Use *world* for all regions
not covered by any polygon.
#. Configure the regionalized magnitude parameters of the magnitude-region
profile. Activate the *enable* parameter if you wish to apply this profile.
#. Restart the data processing:
.. code-block:: sh
seiscomp restart
or execute a GUI module.
.. important::
* Parameters which can be configured along with regionalization assume
defaults from global binding parameters but override global bindings
parameters when configured.
* Once regionalization is active, magnitudes for events outside the
defined region(s) will not be computed. For considering such events add
another magnitude-region profile with the name "*world*".
Magnitudes for events outside any other magnitude-region profile will then
be computed according to this profile.
Setup: station corrections
~~~~~~~~~~~~~~~~~~~~~~~~~~
:ref:`Magnitude station corrections <concepts-magnitudes-correction>` can also
be applied in case of reBy regionalization, magnitudes can be computed with region-dependent properties.
Regions are defined by polygons in BNA or GeoJSON files which must be known to
|scname|.gionalization. Simply add the names of the
magnitude-region profile along with the correction parameter to the original
parameter in global module configuration, :file:`global.cfg`, for the respective
magnitude type and station. Use comma separation for multiple regions and colon
for separating the region name from the value.
Example for correcting MLv computed at station GE.UGM:
.. code-block:: properties
module.trunk.GE.UGM.magnitudes.MLv.offset = 0.1, europe:0.2, asia:-0.1
.. note::
The configuration of parameters starting with *module.trunk.* is not
supported by :ref:`scconfig`. All corresponding configurations must be done
by directly editing the configuration file, e.g.,
:file:`seiscomp/etc/global.cfg`.
Application
~~~~~~~~~~~
When configured, regionalization is automatically applied when computing
magnitudes in :ref:`scmag` or :ref:`scolv`.
.. _tutorials_mags_regionalize_testing:
Testing
~~~~~~~
* Regionalization:
#. Start :ref:`scolv` with the option :option:`--debug` and load an event of
interest
.. code-block:: sh
scolv --debug
#. Relocate the event for generating a new origin.
#. Compute magnitudes selecting the magnitude of interest.
#. Inspect the computed magnitudes in the
:ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
debug output listing the considered magnitudes and stations along with
the regionalized parameters.
.. _tutorials_amplitude-aliases:
Amplitude Aliases
=================
Amplitude aliases are new amplitude types based original ones. Such aliases
allow their specific configuration and computation. They can be created and
independent of magnitudes by :ref:`scautopick` and :ref:`scamp` and used for
:ref:`magnitude aliases <tutorials_magnitude-aliases>`.
.. note::
Amplitude aliases make use of the same parameter structure as the initial
amplitude but the parameters must be configured independently.
Setup
-----
#. Global module configuration: Define the alias name in :confval:`amplitudes.aliases`.
Format and example:
.. code-block:: properties
amplitudes.aliases = alias:original amplitude type
amplitudes.aliases = MLc01:MLc
#. Configure the amplitude bindings parameters. The parameters are identical to
those of the original amplitude type except that the name of the original
magnitude must be replaced by the name of the alias. You may thus first
configure the original amplitude and then replace the name.
**Example binding configuration** for MLc01 derived from MLc:
.. code-block:: properties
amplitudes.MLc01.preFilter = BW(3,0.5,12)
amplitudes.MLc01.applyWoodAnderson = true
...
amplitudes.MLc01.enable = true
amplitudes.MLc01.enableResponses = false
amplitudes.MLc01.minSNR = 1.5
amplitudes.MLc01.signalBegin = -1
amplitudes.MLc01.signalEnd = min(tt(S) + 10, 150)
...
amplitudes.MLc01.maxDepth = 50
Repeat the action for all applicable binding profiles.
Instead of adjusting the bindings profiles you may add the configuration to
global or any other module configuration by prepending
*module.trunk.[module]* where *[module]* is to be replaced by the name of the
module including *global*.
**Example global module configuration** in :file:`global.cfg`:
.. code-block:: properties
module.trunk.global.amplitudes.MLc01.preFilter = BW(3,0.5,12)
module.trunk.global.amplitudes.MLc01.applyWoodAnderson = true
...
module.trunk.global.amplitudes.MLc01.enable = true
module.trunk.global.amplitudes.MLc01.enableResponses = false
module.trunk.global.amplitudes.MLc01.minSNR = 1.5
module.trunk.global.amplitudes.MLc01.signalBegin = -1
module.trunk.global.amplitudes.MLc01.signalEnd = min(tt(S) + 10, 150)
...
module.trunk.global.amplitudes.MLc01.maxDepth = 50
Configuration of bindings profiles has the advantage that the parameters are
available on any client connected to the messaging including external
SeisComP systems. Writing to global module configuration may be more simple
than maintaining multiple bindings profiles but the configuration is not
available to clients in external computers/SeisComP systems.
Application
-----------
* For automatic measurement by :ref:`scautopick` or :ref:`scamp` add the alias
name to the list of measured amplitudes in the corresponding module
configuration.
* For using the measured amplitude value with magnitudes, create a
:ref:`magnitude alias <tutorials_magnitude-aliases>`.
Testing
-------
Compute amplitudes with :ref:`scamp` or by magnitude aliases in :ref:`scolv` and
read the debug log output as when testing
:ref:`magnitude aliases <tutorials_mags_aliases_testing>`.
.. _tutorials_magnitude-aliases:
Magnitude Aliases
=================
Magnitude aliases are new magnitude types based original ones. Such aliases
allow their specific configuration and computation. They can be created from
magnitude and amplitude types native in |scname| or from
:ref:`amplitude aliases <tutorials_amplitude-aliases>` which must be defined
first. Unless specified explicitly, the amplitude type
is the base amplitude of the original magnitude.
Other amplitude types or amplitude aliases must be defined first and given
explicitly.
.. note::
Magnitude aliases make use of the same parameter structure as the initial
magnitude but the parameters must be configured independently.
Setup
-----
#. Create a magnitude alias in :file:`global.cfg` by configuring
:confval:`magnitudes.aliases`.
Format:
.. code-block:: properties
magnitudes.aliases = alias:original magnitude type[:amplitude type]
The amplitude type is optional and can be omitted when equal to the type of
the original magnitude.
Example for an alias magnitude, MLc1, derived from the MLc magnitude and
amplitude. Since initial amplitudes and magnitudes are identical, the
amplitude type can be dropped:
.. code-block:: properties
magnitudes.aliases = MLc01:MLc:MLc
magnitudes.aliases = MLc01:MLc
Example for an alias magnitude, MLc1, derived from the MLc magnitude and
amplitude. Since initial amplitudes and magnitudes are different, the
amplitude type must be given and
:ref:`configured independently <tutorials_amplitude-aliases>`
.. code-block:: properties
magnitudes.aliases = MLc01:MLc:MLc01
#. Configure the alias amplitude if any is used.
#. Configure the alias magnitude in **either** way:
* **Adjust binding profiles:** Configure global bindings parameters by
directly adjusting binding profiles.
Parameters of original magnitudes which are supported by magnitude-type
profiles can be set for the magnitude alias in :ref:`scconfig` by creating
a new magnitude-type profile having the name of the magnitude alias.
All other parameters must be written to the binding parameter files using
an external text editor:
#. Read the relevant parameter names of the original magnitude from global
binding, e.g., in :ref:`scconfig` or the binding parameter file.
Parameter names must include the full hierarchy including all sections.
Example for parameter name of original magnitude:
.. code-block:: properties
magnitudes.MLc.parametric.c1
#. Edit all relevant binding parameter files, e.g.,
:file:`seiscomp/etc/key/global/profile_HHZ` in a text editor and set the
values for the alias magnitude. For default values, the parameters do not
need to be set.
Example of resulting parameter for alias magnitude MLc01:
.. code-block:: properties
magnitudes.MLc01.parametric.c1 = 0.6
* **Regionalization:** Set up by :ref:`regionalization <tutorials_magnitude-region>`.
* Consider the tutorial above on
:ref:`magnitude regionalization <tutorials_magnitude-region>`.
* For the name of new magnitude-type profiles now use the new alias name.
.. hint::
When initially configuring amplitude and magnitude aliases, :ref:`scconfig`
does not know which original amplitude and magnitude types are considered and
the corresponding parameters may not be accessible.
The full list of parameters of the alias can, however, be derived from
original types:
#. Open scconfig and configure the original amplitude and magnitude
referenced by the alias.
#. Close scconfig.
#. Open the binding or module configuration file, e.g.,
:file:`seiscomp/etc/key/global/profile_HHZ` or :file:`global.cfg`.
#. Copy or rename the name of the referenced amplitude or magnitude in the
parameters to the name of the alias.
#. Open scconfig. The new parameters are now visible along with the
original one and can be adjusted. You may now remove all
irrelevant parameters of the original magnitude.
This procedure applies to the adjustment of binding profiles and to
regionalization except that regionalization only supports magnitudes.
* **Write bindings parameters to global module configuration:** Manually
adjust the module configuration file, e.g., :file:`global.cfg`. The
operation is not supported by :ref:`scconfig`.
#. Read the relevant parameter names of the original magnitude from global
binding, e.g., in :ref:`scconfig`. The names must include the full
hierarchy including all sections. Example:
.. code-block:: properties
magnitudes.MLc01.parametric.c1
#. Open the module configuration file, e.g.,
:file:`seiscomp/etc/global.cfg` in a text editor.
#. Prepend *module.trunk.global.* to the parameter name and add it along with
its value to the configuration file for all networks and stations.
Example:
.. code-block:: properties
module.trunk.global.magnitudes.MLc01.parametric.c1 = 0.7
For a given network or network and station replace *global* by the
*network* or the *network* and the *station* code. Example for network
CX and station PB01:
.. code-block:: properties
module.trunk.CX.PB01.magnitudes.MLc01.parametric.c1 = 0.7
module.trunk.CX.magnitudes.MLc01.parametric.c1 = 0.7
#. Add the new magnitude name to the configuration of all relevant modules,
e.g., :ref:`scamp`, :ref:`scmag`, :ref:`scevent`, :ref:`scolv`.
.. note::
The parameters starting with *module.trunk.* are not available for
configuration in :ref:`scconfig`.
.. warning::
Binding parameters configured in global module configuration should only
be considered exceptionally. These parameters will
* Override the corresponding parameters configured by regionalization
using the region *world*.
* Not be written to the database and cannot be accessed by SeisComP
modules running on other computers.
Application
-----------
* For automatic computation by :ref:`scmag` add the alias name to the list of
measured magnitudes in the corresponding module configuration.
* For interactive computation choose the magnitude alias name in :ref:`scolv`
when computing magnitudes. The alias may be added to the default magnitudes in
the scolv module configuration.
.. _tutorials_mags_aliases_testing:
Testing
-------
#. Start :ref:`scolv` with the option :option:`--debug` and load an event of
interest
.. code-block:: sh
scolv --debug
#. Relocate the event for generating a new origin.
#. Compute magnitudes selecting the magnitude of interest including the new
alias.
#. Inspect the computed magnitudes in the
:ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
debug output listing the considered magnitude names and aliases along with
the considered parameters and their values. Example where MLc1 is derived
from MLc with a modified maximum depth:
.. code-block:: sh
...
13:30:46 [debug] GE.UGM: MLc1: effective correction (no locale) = 1.00:0.00
13:30:46 [debug] Parameters for magnitude MLc1
13:30:46 [debug] + maximum depth: 50.000 km
13:30:46 [debug] + distance mode: hypocentral
13:30:46 [debug] + minimum distance: -1.000 km
13:30:46 [debug] + maximum distance: 889.561 km
...
.. _tutorials_mags_moment:
Moment Magnitudes
=================
All magnitudes, Mx, can be mapped to a moment magnitude, Mw(Mx) by piecewise
linear interpolation.
.. warning::
Do not map :term:`mB <magnitude, broadband body-wave (mB)>`
or :term:`Mwp <magnitude, broadband P-wave moment (Mwp)>` to Mw since
this is hardcoded already and done automatically by :ref:`scmag`.
Setup
-----
The configuration procedure is:
#. Set up a magnitude-type profile for the original magnitude type in global
module configuration. Use :ref:`scconfig` for creating the profile.
#. Configure the parameter *MwMapping*, which will become available along with
the new profile, e.g., :confval:`magnitudes.MLc.MwMapping`. Alternatively,
add the parameter to :file:`seiscomp/etc/global.cfg`. The parameter is
configured as a list of sample points of a piecewise linear function mapping
from the original magnitude, Mx, to Mw(Mx).
Example for Mw(MLc) based on MLc:
.. code-block:: properties
magnitudes.MLc.MwMapping = MLc_0:Mw(MLc)_0,MLc_1:Mw(MLc)_1,...,MLc_N:Mw(MLc)_N
Any magnitude value outside the configured range is ignored.
The new moment magnitudes will be available along with the original magnitudes
and can be viewed in :ref:`scolv` or :ref:`scesv` and considered by :ref:`scmag`
or :ref:`scevent`.
In order to avoid that :ref:`summary magnitudes <concepts-magnitudes-summary>`
are computed from original magnitudes and mapped Mw together and biased to both,
the original magnitudes can be blocklisted in :ref:`scmag`
(:confval:`summaryMagnitude.blacklist`).
Application
-----------
* Mapped Mw() magnitudes are automatically computed when configured.
* For consideration in summary magnitudes configure and run :ref:`scmag`.
* For consideration in preferred magnitudes configure and run :ref:`scevent` or
select in :ref:`scolv`.
* For interactive computation choose the original magnitude name in :ref:`scolv`
when computing magnitudes.

226
share/doc/seiscomp/html/_sources/base/tutorials/archiving.rst.txt
View File

@ -1,13 +1,14 @@
.. _tutorials_archiving:
*******************************
Set up local waveform archiving
*******************************
**************************
Maintain waveform archives
**************************
You will ...
* Set up :ref:`slarchive` with its necessary bindings
* Set up `purge_datafiles` in crontab
* Control the life-time of waveforms
* Access waveforms
Pre-requisites for this tutorial:
@ -21,11 +22,12 @@ Pre-requisites for this tutorial:
Afterwards/Results/Outcomes:
* Save real-time data in a local archive for later processing.
* See :term:`miniSEED` day files for GE stations in your local :ref:`waveform archive <concepts_waveformarchives>`.
* See :term:`miniSEED` day files for GE stations in your local
:ref:`waveform archive <concepts_waveformarchives>`.
Time range estimate:
* 5 minutes
* 20 minutes
Related tutorial(s):
@ -34,23 +36,40 @@ Related tutorial(s):
----------
**Motivation**:
Without activating archiving, your local Seedlink server
will only keep waveforms for a short time.
Motivation
==========
Without activating waveform archiving, your local :ref:`Seedlink server <seedlink>`
will only keep waveforms for a short period of time.
This makes it hard to review old events, for example.
:ref:`slarchive` is therefore set up and used for archiving real-time waveforms
from a seedlink server.
In this example, we'll arrange for keeping waveforms for one week.
Before starting, you'll need bindings for your stations;
see the tutorials :ref:`tutorials_geofon_waveforms`
or :ref:`tutorials_waveforms`.
The :program:`slarchive` collects data and archives it
locally using a :term:`SDS` file system structure of
nested subdirectories and systematically named files.
Before starting, you'll need ensure to have access to readl-time data from a
:ref:`seedlink` server. To make seedlink bindings for your stations see the
tutorials :ref:`tutorials_geofon_waveforms` or :ref:`tutorials_waveforms`.
Background
==========
:ref:`slarchive` collects data and archives it locally in the directory defined
by :confval:`archive` using a :term:`SDS` file
system structure of nested subdirectories and systematically named files. For
working with the archived data, read the section on
:ref:`tutorials_archiving-access`.
Setup
=====
:ref:`slarchive` requires a module configuration and bindings.
You may configure slarchive using :ref:`scconfig` or by command-line actions.
In scconfig
===========
-----------
#. Under the Modules tab, go to Acquisition, and select :program:`slarchive`.
Here you can see the default parameters used.
@ -71,11 +90,15 @@ In scconfig
should apply to, under "Networks" on the left-hand side of the
bindings tool.
.. warning:: The name 'week' is just a label.
.. warning::
The name 'week' is just a label.
Its functionality comes from changing the value of the `keep` parameter.
Changing the *name* of a binding profile does not change its function.
.. note:: You can also choose which channels should be archived,
.. note::
You can also choose which channels should be archived,
using the ":confval:`selectors`" box.
For instance, you may collect data at several sample rates,
and only wish to archive the highest rate.
@ -93,17 +116,21 @@ In scconfig
Command line
============
------------
You will need to edit each of your top-level key files to refer to
a new binding profile.
e.g.::
e.g.
.. code-block:: sh
$ cd ~/seiscomp/etc/key
$ vi station_GR_CLL
Add the line `slarchive:week` to whatever lines are already there.
Afterwards it will look something like this::
Afterwards it will look something like this
.. code-block:: properties
# Binding references
global:BH
@ -114,7 +141,9 @@ Afterwards it will look something like this::
Repeat this for the top-level key file of each station
you wish this binding to apply to.
Now create the binding profile in the key directory.
This is a file with a name corresponding to the binding profile name; here: 'week' ::
This is a file with a name corresponding to the binding profile name; here: 'week'
.. code-block:: sh
$ cd ~/seiscomp/etc/key
$ mkdir slarchive
@ -129,66 +158,131 @@ This is a file with a name corresponding to the binding profile name; here: 'wee
slarchive is not running
starting slarchive
.. note::
Left unattended, your disk will eventually fill up with archived data.
To prevent this you will need a script like `purge_database`,
which is provided with SeisComP.
This can be run once per day using the `cron` feature of your system.
The command::
Data life cycle
---------------
$ seiscomp print crontab
Left unattended, your disk will eventually fill up with archived data since
:ref:`slarchive` itself does not delete any data.
will print a number of lines to the terminal.
Type `crontab -e` and insert these lines into the crontab file for your
user (typically `sysop`).
Exit your crontab editor.
Displaying your crontab should now show a line for `purge_database`.::
$ crontab -l
20 3 * * * /home/sysop/seiscomp/var/lib/slarchive/purge_datafiles >/dev/null 2>&1
[There may be other lines too.]
Deleting files
~~~~~~~~~~~~~~
This shows you that the `purge_datafiles` script
will run every day at 3:20 a.m.
To prevent your file system from filling up you may delete data using a script
like `purge_database`, provided with |scname|. The script considers duration set
by the *keep* parameter in slarchive bindings for defining the number of days to
keep the data in your archive.
The script can be run once per day using the `cron` feature of your system.
The command
.. code-block:: sh
$ seiscomp print crontab
will print a number of lines with suggested actions to the terminal. Type
`crontab -e` and insert these lines into the crontab file for your user (typically `sysop`).
Exit your crontab editor.
Displaying your crontab should now show a line for `purge_database`.
.. code-block:: sh
$ crontab -l
20 3 * * * /home/sysop/seiscomp/var/lib/slarchive/purge_datafiles >/dev/null 2>&1
[There may be other lines too.]
This shows you that the `purge_datafiles` script will run every day at 3:20 a.m.
.. note::
If you examine the `purge_datafiles` script, you will see that all it does
is look for files with a last modified time older than a certain number
of days ago.
The number of days to keep can be set station-by-station using the
ARCH_KEEP feature.
A convenient way to do this for many stations is with
multiple binding profiles, one for each length of time desired.
If you examine the `purge_datafiles` script, you will see that all it does
is looking for files with a last modified time older than a certain number
of days ago.
The number of days to keep can be set station-by-station using the
ARCH_KEEP feature.
A convenient way to do this for many stations is with
multiple slarchive binding profiles, one for each length of time desired.
Checking archiving is functioning
=================================
Extending disk space
~~~~~~~~~~~~~~~~~~~~
* If :program:`seedlink` is configured correctly, a new station's streams
appears in output from :program:`slinktool`::
In case your file system fills up with data and you do not wish to delete
old ones, you may add an additional harddisk and configure :confval:`archive`
of :program:`slarchive` to store the new data there. Thereafter you may
configure the *combined* or the *sdsarchive* :ref:`global_recordstream` to read
the data from both sources.
$ slinktool -Q : | grep CLL
GR CLL HHZ D 2020/04/01 01:11:57.6649 - 2020/04/01 07:28:49.0299
GR CLL HHE D 2020/04/01 01:11:57.6649 - 2020/04/01 07:28:45.0299
GR CLL HHN D 2020/04/01 01:11:57.6649 - 2020/04/01 07:28:39.2299
Verification
------------
* If :ref:`seedlink` is configured correctly, a new station's streams
appear in output from :ref:`slinktool`
.. code-block:: sh
$ slinktool -Q : | grep CLL
GR CLL HHZ D 2020/04/01 01:11:57.6649 - 2020/04/01 07:28:49.0299
GR CLL HHE D 2020/04/01 01:11:57.6649 - 2020/04/01 07:28:45.0299
GR CLL HHN D 2020/04/01 01:11:57.6649 - 2020/04/01 07:28:39.2299
This shows three streams being acquired from station 'CLL'.
The second time shown is the time of the most recent data for each stream.
* If :program:`slarchive` is configured correctly, waveform data for the
* If :ref:`slarchive` is configured correctly, waveform data for the
station appears in :program:`slarchive`'s SDS archive directory:
.. code-block:: sh
.. code-block:: sh
$ ls -l seiscomp/var/lib/archive/2020/GR/CLL
total 12
drwxr-xr-x 2 user user 4096 Apr 1 06:30 HHE.D
drwxr-xr-x 2 user user 4096 Apr 1 06:30 HHN.D
drwxr-xr-x 2 user user 4096 Apr 1 06:30 HHZ.D
$ ls -l seiscomp/var/lib/archive/2020/GR/CLL
total 12
drwxr-xr-x 2 user user 4096 Apr 1 06:30 HHE.D
drwxr-xr-x 2 user user 4096 Apr 1 06:30 HHN.D
drwxr-xr-x 2 user user 4096 Apr 1 06:30 HHZ.D
$ ls -l seiscomp/var/lib/archive/2020/GR/CLL/HHZ.D/
total 12728
-rw-r--r-- 1 user user 5492224 Mar 31 00:04 GR.CLL..BHZ.D.2020.090
-rw-r--r-- 1 user user 7531008 Apr 1 00:03 GR.CLL..BHZ.D.2020.091
$ ls -l seiscomp/var/lib/archive/2020/GR/CLL/HHZ.D/
total 12728
-rw-r--r-- 1 user user 5492224 Mar 31 00:04 GR.CLL..BHZ.D.2020.090
-rw-r--r-- 1 user user 7531008 Apr 1 00:03 GR.CLL..BHZ.D.2020.091
You may read these data files directly using :ref:`scrttv`, e.g.:
.. code-block:: sh
$ scrttv seiscomp/var/lib/archive/2020/GR/CLL/HHZ.D/*
.. _tutorials_archiving-access:
Access to Archived Data
=======================
Archived waveforms can be read or provided in multiple ways depending on the
application.
* Offline reading with :ref:`scrttv`: Read miniSEED files directly using
:ref:`scrttv`, e.g.:
.. code-block:: sh
$ scrttv seiscomp/var/lib/archive/2020/GR/CLL/HHZ.D/*
* Automatically for data processing: |scname| modules such as
:ref:`scautopick` or :ref:`scolv` can read data from SDS
archive with the *sdsarchive* :ref:`global_recordstream` when running on the
same computer.
* External clients: You may provide the data to clients on other
computers using :ref:`scwfas` or :ref:`fdsnws` both providing data via
:cite:t:`fdsn`.
* Direct file access: For directly fetching :term:`miniSEED` waveform data from
archive you may use :ref:`scart` or Linux commands. You may combine scart
with other modules avoiding redundant file storage. Examples:
.. code-block:: sh
$ scart -dEsv -t 2025-02-01T01:00~2025-02-01T01:00 /archive | scrttv -
$ scart -dEsv -t 2025-02-01T01:00~2025-02-01T01:00 /archive | scautopick -I - -d localhost --ep --playback

15
share/doc/seiscomp/html/_sources/base/tutorials/geofon_waveforms.rst.txt
View File

@ -52,13 +52,13 @@ Check data are available
========================
First, we'll query the upstream Seedlink server, which runs on
host `geofon.gfz-potsdam.de` at port 18000.
host *geofon.gfz.de* at port *18000*.
We do this with SeisComP's :ref:`slinktool` command, giving the ``-L`` option
to :ref:`slinktool`
.. code-block:: sh
$ slinktool -L geofon.gfz-potsdam.de
$ slinktool -L geofon.gfz.de
6C GF01 GF01
6C GF02 GF02
6C GF03 GF03
@ -76,7 +76,7 @@ code GE
.. code-block:: sh
$ slinktool -Q geofon.gfz-potsdam.de | grep ^GE.*BHZ
$ slinktool -Q geofon.gfz.de | grep ^GE.*BHZ
GE ACRG BHZ D 2019/11/28 06:51:48.7500 - 2019/11/28 09:18:32.1000
GE APE BHZ D 2019/11/28 07:40:52.0400 - 2019/11/28 12:22:00.3950
GE ARPR BHZ D 2019/11/27 23:23:27.4400 - 2019/11/28 09:41:22.1500
@ -130,7 +130,7 @@ StationXML format.
.. code-block:: sh
$ wget "http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=GE&level=response" -O ge.xml
$ wget "http://geofon.gfz.de/fdsnws/station/1/query?net=GE&level=response" -O ge.xml
Option 2: Using WebDC3
@ -144,7 +144,7 @@ from different data centres among other possibilities.
You can find detailed information about WebDC3 in the on-line documentation at
:cite:t:`webdc3-documentation`.
* Go to http://eida.gfz-potsdam.de/webdc3 with a browser.
* Go to http://eida.gfz.de/webdc3 with a browser.
* Click on "Explore stations" and move the slider to select only the current year
and only "Public permanent nets" on the Network type list.
@ -335,10 +335,9 @@ References
.. target-notes::
.. [#WebDC] The WebDC3 service is available at http://eida.gfz-potsdam.de.
See also
.. [#WebDC] The WebDC3 service is available at http://eida.gfz.de. See also
M. Bianchi, *et al.* (2015): WebDC3 Web Interface. GFZ Data Services.
doi:`10.5880/GFZ.2.4/2016.001 <http://dx.doi.org/10.5880/GFZ.2.4/2016.001>`_
.. [#NETPAGES] For instance that of the GEOFON Program, at
https://geofon.gfz-potsdam.de/waveform/archive/network.php?ncode=GE.
https://geofon.gfz.de/waveform/archive/network.php?ncode=GE.

278
share/doc/seiscomp/html/_sources/base/tutorials/magnitude-regionalization.rst.txt
View File

@ -1,278 +0,0 @@
.. _tutorials_magnitude-region-aliases:
****************************************
Magnitudes: Regionalization, Aliases, Mw
****************************************
You will ...
* Regionalize magnitude
* Create new magnitude types as aliases from other magnitudes and amplitudes.
* Map magnitudes to the moment magnitude, Mw
:Pre-requisites for this tutorial:
* Read the :ref:`concepts section on magnitudes <concepts_magnitudes>`.
* Real-time data for the station must be available locally.
See :ref:`tutorials_waveforms` or :ref:`tutorials_geofon_waveforms`.
* Inventory must be loaded locally.
:Afterwards/Results/Outcomes:
* Regionalized magnitudes,
* New magnitude types as aliases.
* Moment magnitudes
:Time range estimate:
* 30 minutes
-----------
.. _tutorials_magnitude-region:
Regionalize Magnitudes
======================
By regionalization, magnitudes can be computed with region-dependent properties.
The procedure to set up magnitude regionalization is:
#. Create one file which contains the polygons surrounding the regions within
which magnitude parameters shall apply. The polygon files are provided in
:ref:`BNA <sec-gui_layers-vector-format-bna>` or
:ref:`GeoJSON format <sec-gui_layers-vector-format-geojson>` and located as
set out in the :ref:`documentation of map layers <sec-gui_layers>`. The file
can be created from any |scname| GUI application providing maps, e.g.,
:ref:`scmv`.
#. For the desired magnitude type create a magnitude-type profile in global
module configuration. The name of the profile matches the name of the
magnitude, e.g., *MLc* for the :ref:`MLc magnitude <global_mlc>`.
#. Configure the :confval:`magnitudes.MLc.regionFile` parameter with the full
path and name of the polygon file created above.
#. Within the magnitude-type profile create one or more magnitude-region
profile(s) for defining the regionalized parameters applied to the region(s).
The name of a profile corresponds to the name of the polygon contained in the
polygon file to which the parameters shall apply. Use *world* for all regions
not covered by any polygon.
#. Configure the regionalized magnitude parameters of the magnitude-region
profile. Activate the *enable* parameter if you wish to apply this profile.
#. Restart the data processing:
.. code-block:: sh
seiscomp restart
or execute a GUI module.
.. important::
* Parameters which can be configured along with regionalization assume
defaults from global binding parameters but override global bindings
parameters when configured.
* Once regionalization is active, magnitudes for events outside the
defined region(s) will not be computed. For considering such events add
another magnitude-region profile with the name "*world*".
Magnitudes for events outside any other magnitude-region profile will then
be computed according to this profile.
Station corrections
-------------------
:ref:`Magnitude station corrections <concepts-magnitudes-correction>` can also
be applied in case of regionalization. Simply add the names of the
magnitude-region profile along with the correction parameter to the original
parameter in global module configuration, :file:`global.cfg`, for the respective
magnitude type and station. Use comma separation for multiple regions and colon
for separating the region name from the value.
Example for correcting MLv computed at station GE.UGM:
.. code-block:: properties
module.trunk.GE.UGM.magnitudes.MLv.offset = 0.1, europe:0.2, asia:-0.1
.. note::
The configuration of parameters starting with *module.trunk.* is not
supported by :ref:`scconfig`. All corresponding configurations must be done
by directly editing the configuration file, e.g.,
:file:`seiscomp/etc/global.cfg`.
.. _tutorials_magnitude-aliases:
Magnitude Aliases
=================
New magnitude types (aliases) can be created based on existing magnitude and
amplitude types but configured specifically.
The procedure to set up magnitude aliases is:
#. Create a magnitude alias in :file:`global.cfg` by configuring
:confval:`magnitudes.aliases`. Example:
.. code-block:: properties
magnitudes.aliases = MLc1:MLc:MLc
#. Configure the alias magnitudes in either way:
* Write bindings parameters to global module configuration or
* Set up :ref:`regionalization <tutorials_magnitude-region>`:
**Binding parameters in global module configuration:**
#. Read the relevant parameter names of the original magnitude from global
binding, e.g., in :ref:`scconfig`. The names must include the full
hierarchy including all sections. Example:
.. code-block:: properties
magnitudes.MLc01.parametric.c1
#. Open the module configuration file, e.g.,
:file:`seiscomp/etc/global.cfg` in a text editor.
#. Prepend *module.trunk.global.* to the parameter name and add it along with
its value to the configuration file. Example:
.. code-block:: properties
module.trunk.global.magnitudes.MLc01.parametric.c1 = 0.7
#. Add the new magnitude name to the configuration of all relevant modules,
e.g., :ref:`scamp`, :ref:`scmag`, :ref:`scevent`, :ref:`scolv`.
.. note::
The parameters starting with *module.trunk.* are not available for
configuration in :ref:`scconfig`.
.. warning::
Binding parameters configured in global module configuration should only
be considered exceptionally. These parameters will
* Override the corresponding parameters configured by regionalization
using the region *world*.
* Not be written to the database and cannot be accessed by SeisComP
modules running on other computers.
**Regionalization:**
* Consider the tutorial on
:ref:`magnitude regionalization <tutorials_magnitude-region>` above.
* For the name of the new magnitude-type profile now use the alias name.
.. hint::
When adding the magnitude-region profile in
:ref:`scconfig`, scconfig does not know about the referenced original
magnitude. Therefore, not all possible configuration parameters may be
listed depending on the magnitude, e.g. for MLc. For getting the full
list, first create and configure a magnitude-region profile for the
referenced magnitude.
#. Close scconfig
#. Open the configuration file :file:`global.cfg`
#. Rename the name of the referenced magnitude in the parameters to the
name of the alias.
.. _tutorials_mags_moment:
Moment Magnitudes
=================
All magnitudes, Mx, can be mapped to a moment magnitude, Mw(Mx).
The configuration procedure is:
#. Set up a magnitude-type profile for the original magnitude type in global
module configuration. Use :ref:`scconfig` for creating the profile.
#. Configure the parameter *MwMapping*, which will become available along with
the new profile, e.g., :confval:`magnitudes.MLc.MwMapping`. Alternatively,
add the parameter to :file:`seiscomp/etc/global.cfg`. The parameter is
configured as a list of sample points of a piecewise linear function mapping
from the original magnitude, Mx, to Mw(Mx).
Example for Mw(MLc) based on MLc:
.. code-block:: properties
magnitudes.MLc.MwMapping = MLc_0:Mw(MLc)_0,MLc_1:Mw(MLc)_1,...,MLc_N:Mw(MLc)_N
Any magnitude value outside the configured range is ignored.
.. warning::
Do not map the magnitudes :term:`mB <magnitude, broadband body-wave (mB)>`
and :term:`Mwp <magnitude, broadband P-wave moment (Mwp)>` to Mw since
this is hardcoded already and done automatically by :ref:`scmag`.
The new moment magnitudes will be available along with the original magnitudes
and can be viewed in :ref:`scolv`or :ref:`scesv` and considered by :ref:`scmag`
or :ref:`scevent`.
In order to avoid that :ref:`summary magnitudes <concepts-magnitudes-summary>`
are computed from original magnitudes and mapped Mw together and biased to both,
the original magnitudes can be blocklisted in :ref:`scmag`
(:confval:`summaryMagnitude.blacklist`).
.. _tutorials_mags_regionalize_testing:
Final Tests
===========
* Regionalization:
#. Start :ref:`scolv` with the option :option:`--debug` and load an event of
interest
.. code-block:: sh
scolv --debug
#. Relocate the event for generating a new origin.
#. Compute magnitudes selecting the magnitude of interest.
#. Inspect the computed magnitudes in the
:ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
debug output listing the considered magnitudes and stations along with
the regionalized parameters.
* Magnitude aliases:
#. Start :ref:`scolv` with the option :option:`--debug` and load an event of
interest
.. code-block:: sh
scolv --debug
#. Relocate the event for generating a new origin.
#. Compute magnitudes selecting the magnitude of interest including the new
alias.
#. Inspect the computed magnitudes in the
:ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
debug output listing the considered magnitude names and aliases along with
the considered parameters and their values. Example where MLc1 is derived
from MLc with a modified maximum depth:
.. code-block:: sh
...
13:30:46 [debug] GE.UGM: MLc1: effective correction (no locale) = 1.00:0.00
13:30:46 [debug] Parameters for magnitude MLc1
13:30:46 [debug] + maximum depth: 50.000 km
13:30:46 [debug] + distance mode: hypocentral
13:30:46 [debug] + minimum distance: -1.000 km
13:30:46 [debug] + maximum distance: 889.561 km
...

69
share/doc/seiscomp/html/_sources/base/tutorials/postinstall.rst.txt
View File

@ -6,11 +6,14 @@ Installation on Ubuntu
You will ...
* Make a basic |scname| installation
* Make a basic |scname| installation of SeisComP in version 4.0.0 on Ubuntu 20.04
* Make an initial configuration
* Perform function tests
Pre-requisites for this tutorial:
* Internet access
* :ref:`Documentation of installation <installation>`
Afterwards/Results/Outcomes:
@ -51,18 +54,20 @@ but the steps for other Ubuntu versions are similar.
$ sudo addgroup admin
$ sudo usermod -a -G admin,adm,audio sysop
.. note:
.. note::
Adding a new user is not mandatory. You can install under an existing user
directory. Creating a new user is recommended as it allows an easy cleanup
of the system later simply by removing the new user if needed.
#. Check the size and the architecture. This is espcially required when installing
:ref:`pre-compiled packages<tutorials_postinstall_package>`: ::
:ref:`pre-compiled packages<tutorials_postinstall_package>`:
$ df -h
$ cat /etc/issue
$ uname -m
.. code-block:: sh
$ df -h
$ cat /etc/issue
$ uname -m
Compare the available disk space with the requirements given in
the :ref:`installation` section.
@ -75,9 +80,10 @@ but the steps for other Ubuntu versions are similar.
Install from source code
========================
To compile SeisComP from the source code follow the
:ref:`instructions in the development section <build>`. You may later download and add
maps as described below in the :ref:`package section <tutorials_postinstall_package>`.
To compile |scname| from the source code follow the
:ref:`instructions in the development section <build>`. You may later download
and add maps as described below in the
:ref:`Documentation of installation <installation>`.
.. _tutorials_postinstall_package:
@ -85,7 +91,18 @@ maps as described below in the :ref:`package section <tutorials_postinstall_pack
Install pre-compiled release packages
=====================================
You may download and installed pre-compile SeisComP binary package, maps and documentation.
You may install the |scname| packages in either way:
* :ref:`gsm<installation-gsm>` (recommended) a package manager provided by
:cite:t:`gempa`,
* :ref:`manually by extracting packages <installation-manual>`.
Here we refer to the manual extraction of packages. More details are given
in section :ref:`installation`.
You may download and installed pre-compile |scname| binary package, maps and
documentation.
#. Download the appropriate |scname| binary package taking into
account your Linux distribution and the architecture.
@ -99,15 +116,16 @@ You may download and installed pre-compile SeisComP binary package, maps and doc
.. code-block:: sh
wget "https://www.seiscomp.de/downloader/seiscomp-maps.tar.gz"
$ wget "https://www.seiscomp.de/downloader/seiscomp-maps.tar.gz"
* the documentation package. Make sure, the documentation matches your
SeisComP version.
|scname| version.
.. note::
The |scname| packages received from gempa GmbH contain the documentation
for the respective version and no separate download is required.
The |scname| packages received from :cite:t:`gempa-download` contain the
documentation for the respective version and no separate download is
required.
#. Untar the :file:`seiscomp*` files (binary package, maps and documentation)
you will find in your home or downloads directory. For SeisComP in version
@ -180,7 +198,7 @@ You may download and installed pre-compile SeisComP binary package, maps and doc
For PostgreSQL, also see the detailed :ref:`installation` instructions.
.. warning ::
.. warning::
For Ubuntu 18.04 and newer, take care with MariaDB/MySQL installation.
Before the next step, you must set a root password *for MariaDB/MySQL*
@ -250,14 +268,14 @@ Find a detailed description in section :ref:`getting-started` and short guide be
.. hint::
If, when you attempt to run a SeisComP command such as :ref:`scconfig` or
If, when you attempt to run a |scname| command such as :ref:`scconfig` or
:ref:`scolv`, you receive an error message like
.. code-block:: sh
scconfig: command not found
then the most likely explanation is that you have not set your SeisComP
then the most likely explanation is that you have not set your |scname|
environment variables correctly.
Run the `seiscomp` command with the full path to
@ -278,7 +296,7 @@ Find a detailed description in section :ref:`getting-started` and short guide be
Datacenter ID. These are used for Arclink and Seedlink, and in the information
describing data model objects such as origins and events.
#. The `seiscomp` command is a wrapper, which controls the SeisComP modules.
#. The `seiscomp` command is a wrapper, which controls the |scname| modules.
See :ref:`system-management`.
Run something by typing seiscomp followed by a command
@ -296,15 +314,22 @@ Find a detailed description in section :ref:`getting-started` and short guide be
Use 'help [command]' to get more help about a command
#. Start :ref:`scmaster`.
#. Start and test :ref:`scmaster`.
As described in the :ref:`overview`, these are needed for
communication between the SeisComP database and the individual
SeisComP modules.
communication between the |scname| database and the individual
|scname| modules.
.. code-block:: sh
$ seiscomp start scmaster
starting scmaster
$ seiscomp status scmaster
In case errors are reported you should understand the full debug log:
.. code-block:: sh
$ scmaster --debug
#. Install all dependencies needed for the GUI
@ -333,7 +358,7 @@ Find a detailed description in section :ref:`getting-started` and short guide be
$ seiscomp exec scrttv
After seeing the SeisComP splash screen,
After seeing the |scname| splash screen,
you'll likely get an error message "Could not read inventory (NULL)".
After a new installation, that's okay.
Click that box away, and you'll see a screen with

4
share/doc/seiscomp/html/_sources/base/tutorials/servefdsnws.rst.txt
View File

@ -127,12 +127,12 @@ Check it Works
Further Information
===================
* The `URL Builder at GEOFON <https://geofon.gfz-potsdam.de/waveform/builder.php>`_
* The `URL Builder at GEOFON <https://geofon.gfz.de/waveform/builder.php>`_
lets you fill out a form to tailor your request.
The URL to use to make your request is displayed at the bottom of that page.
* More example requests are at the
`FDSNWS description at GEOFON <https://geofon.gfz-potsdam.de/waveform/webservices.php>`_
`FDSNWS description at GEOFON <https://geofon.gfz.de/waveform/webservices.php>`_
* The FDSN Web Services specification document :cite:p:`fdsn-specs` provides the
technical documentation and examples.

301
share/doc/seiscomp/html/_sources/base/tutorials/upgrading.rst.txt
View File

@ -1,17 +1,19 @@
.. _tutorials_upgrade:
******************
Upgrading SeisComP
******************
***************************
Updating/Upgrading SeisComP
***************************
You will ...
* Upgrade a SeisComP system
* Update/Upgrade a SeisComP system
* Migrate a SeisComP3 system to a newer SeisComP version
Pre-requisites for this tutorial:
* Tutorial on :ref:`installation <tutorials_postinstall>` and SeisComP previously installed
* :ref:`Documentation of installation <installation>`
* Tutorial on :ref:`installation <tutorials_postinstall>` and |scname|
previously installed
Afterwards/Results/Outcomes:
@ -28,9 +30,10 @@ Background
==========
Installing a new SeisComP :ref:`release version <tutorials_upgrade_versions>`
is typically simple and the step described in :ref:`tutorials_upgrade-normal`
can be applied. **More actions** are required when
Updating/upgrading |scname| to a higher
:ref:`release version <installation_versions>` is typically simple and the
steps described in :ref:`tutorials_upgrade-normal` can be applied.
**More actions** are required when
* Upgrading the major version of SeisComP as described in :ref:`tutorials_upgrade-normal`.
* Upgrading :ref:`from SeisComP3 to SeisComP in version 4.0.0. or higher <tutorials_upgrade_v4>`.
@ -38,66 +41,32 @@ can be applied. **More actions** are required when
SeisComP in version 4 or higher <tutorials_upgrade_seedlink>`.
.. _tutorials_upgrade_versions:
Upgrade vs. update
------------------
SeisComP versions
-----------------
SeisComP has :ref:`developed over time <history>`. The versions can be distinguished
by the name of the release:
* **SeisComP since version 4.0.0** uses release version numbers such as *5.2.1*
where
* 5: major version with changes in API and database schema version, new features,
bug fixed, optimizations,
* 2: minor version with new features, bug fixed, optimizations,
* 1: patch number with bug fixes, optimizations.
.. note ::
When increasing the major version number, an upgrade of
the database is required.
* **SeisComP3** uses release versions, names, numbers and patch numbers.
Full example: *SeisComP3-jakarta-2020.330.02*
* 3: release version
* jakarta: release name
* 2020.330: release number
* 02: patch number
Names are adjusted depending on changes in source code:
* **Release version:** major changes in module groups, functionality, concepts, data model.
Example: SeisComp3 is SeisComP in version 3.0
in comparison to version 2.5 the GUIs were introduced.
* **Release name:** major changes in functionality, concepts, data model.
Example: with SeisComP3-Seattle the new user friendly configuration GUI :ref:`scconfig`
was introduced.
* **Release number:** changes in data model version and/or major changes in applications and optimizations.
The numbers include the year and the day of the year of the software release.
Example: Jakarta-2018.327
* **Patch number:** optimizations of applications without changes in the data model version.
Here we understand that *upgrades* increase the major release version number
while *updates* only increase the minor version or the patch number, see section
:ref:`installation_versions`.
Upgrade SeisComP on multiple machines
-------------------------------------
Upgrading multiple machines
---------------------------
Applications can only connect to a messaging system that runs with a database
in an equal or lower data base schema version. In distributed |scname| systems
one machine host the messaging system and the database and all other machines
are connected to this messaging or are running independently, the |scname|
installation on the machine operating the messaging is always updated last.
in an equal or lower data base schema version. However, upgrading |scname| to a
higher major release version typically increases the database scheme version.
Therefore, in distributed |scname| systems where one machine hosts the messaging
system and the database and all other machines are connected to this messaging,
the |scname| installation on the machine operating the messaging is always
upgraded last.
**Example:** A distributed system includes a processing system with the
messaging system and database and a GUI work station connected to the processing
system:
#. Upgrade the GUI work station
#. Upgrade the processing system, take actions to
:ref:`upgrade the database version <tutorials_upgrade-db>`.
#. :ref:`Upgrade <tutorials_upgrade-normal>` the GUI work station
#. :ref:`Upgrade <tutorials_upgrade-normal>` the processing system, take actions
to :ref:`upgrade the database version <tutorials_upgrade-db>`.
.. note::
@ -110,98 +79,50 @@ system:
.. _tutorials_upgrade_download:
Package Download
================
Package download
----------------
Get the SeisComP package in the latest version or older ones from gempa GmbH or
from the download website of :cite:t:`seiscomp`.
.. note ::
gempa provides :cite:t:`gsm` for convenient and consistent download and
installation of SeisComP and other packages.
Get and install the |scname| package in the any available version from
:cite:t:`gempa` or from the download website of :cite:t:`seiscomp` as described
in section :ref:`installation-packages`.
.. _tutorials_upgrade_changelog:
Documentation of Changes
========================
Documentation of changes
------------------------
The important novelties, optimizations and changes that are available after upgrading
are documented in the change log which can be read
`online <https://www.seiscomp.de/doc/base/changelog.html>`_.
It is recommend to read the change log before taking further actions.
The details can also be found locally in the file
.. code-block:: sh
$SEISCOMP_ROOT/share/doc/seiscomp/CHANGELOG
which is integrated in the :ref:`documentation <sc-changelog>` or accessible
from the *Docs* panel in :ref:`scconfig`.
The important novelties, optimizations and changes that are available after
upgrading are documented in the Changelog which is part of this documentation
and which can also be accessed through the *Docs* panel of :ref:`scconfig`.
The installed locally installed file is
:file:`$SEISCOMP_ROOT/share/doc/seiscomp/CHANGELOG`
The Changelog can also be read
`online <https://www.seiscomp.de/doc/base/changelog.html>`_ but care should be
take that the version number matches your.´
.. note::
New features are regularly advertised and described in detail on the
`News website of gempa GmbH <https://www.gempa.de/news/>`_ and on the
:cite:t:`seiscomp-forum`.
.. _tutorials_upgrade-normal:
Normal Upgrade
==============
The normal upgrade including upgrading the major version of SeisComP takes only
a few steps:
#. :ref:`Download <tutorials_upgrade_download>` the SeisComP package.
#. Stop all SeisComP modules:
.. code-block:: sh
seiscomp stop
#. Install the new packages.
.. note::
Users of external, e.g., |gempa| modules must ensure that these external
modules match the SeisComP release version if they depend on SeisComP
libraries.
#. Test the database schema version and update bindings
.. code-block:: sh
seiscomp update-config
:ref:`Upgrade the database schema version <tutorials_upgrade-db>` if
mismatches are reported.
#. After a successful upgrade, start all modules again and observe the status:
.. code-block:: sh
seiscomp start
seiscomp status started
New major release with the features are regularly advertised and described in
detail on the `News website of gempa GmbH <https://www.gempa.de/news/>`_ and
on the :cite:t:`seiscomp-forum`.
.. _tutorials_upgrade-db:
Upgrade database schema version
===============================
-------------------------------
When installing a new SeisComP release with a higher major version number,
upgrading the database may be required. The database version will be tested and
the required actions will be shown when executing:
When upgrading |scname| to a higher major version number as set out in section
:ref:`tutorials_upgrade-normal`, upgrading the database schema is typically
required, too. The database version will be tested and the required actions will
be reported when executing:
.. code-block:: sh
seiscomp update-config
seiscomp update-config**Special case:**
or when pressing the Update Configuration button in scconfig.
or when pressing the Update Configuration button in :ref:`scconfig`.
An upgrade from version SeisComP3 jakarta-2017.334 to SeisComP in version 5.1.0
will give, e.g.:
@ -219,12 +140,22 @@ will give, e.g.:
* migration to the current version is required. apply the following
scripts in exactly the given order:
* mysql -u sysop -p -D seiscomp -h localhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_10_to_0_11.sql
* mysql -u sysop -p -D seiscomp -h localhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_11_to_0_12.sql
* mysql -u sysop -p -D seiscomp -h l
**Special case:**ocalhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_11_to_0_12.sql
error: updating configuration for scmaster failed
The shown migration scripts can be used directly as given and in the given order:
The shown migration scripts can be used directly as given and in the given
order but you need to first stop all modules writing to or deleting objects from
the database such as :ref:`scmaster`, :ref:`scdb`, :ref:`scardac` or
:ref:`scdbstrip` running on the same or any connected machine, e.g.
* MySQL / MariaDB:
.. code-block:: sh
seiscomp stop scmaster
**Special case:**
Thereafter, apply the migration according to your database:
* MySQL/MariaDB:
.. code-block:: sh
@ -239,13 +170,15 @@ The shown migration scripts can be used directly as given and in the given order
psql -U sysop -d seiscomp -h localhost -W -f /home/sysop/seiscomp/share/db/migrations/postgresql/0_11_to_0_12.sql
Using the migration scripts provides a more user friendly way than copying the
lines of MySQL code from the changelog. In future versions we might add the option
lines of MySQL code from the changelog which was practise in past SeisComP3
versions. In future versions we might add the option
to automatically run the migrations.
.. warning::
Upgrading the database make take some time. Do no interrupt the process!
During this time, the |scname| messaging system is unavailable causing a downtime of the system.
During this time, the |scname| messaging system is unavailable causing a
downtime of the system.
After applying the migration scripts the database should be at the correct version.
Test again with:
@ -254,16 +187,77 @@ Test again with:
seiscomp update-config
After successfully upgrading the database continue your previous upgrade procedure.
After successfully upgrading the database continue your previous upgrade
procedure.
.. _tutorials_upgrade-normal:
Normal Update/Upgrade
=====================
Normal updates/upgrades of the major version of |scname| takes only a few steps:
#. If you are tracking your |scname| installation using :program:`git`
(recommended), ensure all previous changes are committed and the installation
is clean.
#. Stop all SeisComP modules:
.. code-block:: sh
seiscomp stop
#. Download and install the |scname| package as described in section
:ref:`installation-packages`.
#. Understand the Changelog of the installed |scname| as described in section
:ref:`tutorials_upgrade_changelog`.
#. Infrequently configuration parameters require changes which
are documented in the Changelog. You may also scan your configuration for
deprecated or obsolete configuration parameters or values using
`gempa-checkSCconfig.py <https://data.gempa.de/packages/Public/tools/>`_
provided by :cite:t:`gempa`. Apply changes accordingly.
#. The software dependencies may have changed after upgrading. Install them as
described in section :ref:`software_dependencies`.
#. Test the database schema version and update bindings
.. code-block:: sh
seiscomp update-config
:ref:`Upgrade the database schema version <tutorials_upgrade-db>` if
mismatches are reported. The mismatch reports will also give the upgrade
instructions. Repeat *seiscomp update-config* after upgrading the database
schema version.
**Background:** When upgrading the major |scname| version you
typically need to upgrade the database scheme version.
#. After a successful update/upgrade, start all modules again and observe the
status:
.. code-block:: sh
seiscomp start
seiscomp status started
#. If you are tracking your |scname| installation using :program:`git`
(recommended), commit all changes.
.. _tutorials_upgrade_v4:
SeisComP3 to version >=4
Upgrading from SeisComP3
========================
SeisComP in version 4 has some major differences to SeisComP3 which require adjustments.
The main differences are in the :ref:`directories of the SeisComP installation <sec-tutorials_upgrading_path>`
SeisComP in version >=4 has major differences to SeisComP3 which require
adjustments. The main differences are in the
:ref:`directories of the SeisComP installation <sec-tutorials_upgrading_path>`
and the :ref:`messaging system <sec-tutorials_upgrading_messaging>`.
The changes and the required actions are explained below. They must be considered
in addition to the steps set out in section :ref:`tutorials_upgrade-normal`.
@ -274,8 +268,8 @@ in addition to the steps set out in section :ref:`tutorials_upgrade-normal`.
Files and directories
---------------------
With **SeisComP3** all the default installation typically required all modules and configurations
in the directories
With **SeisComP3** all the default installation typically required all modules
and configurations in the directories
* seiscomp3/ , typically $HOME/seiscomp3 or /opt/seiscomp3/
* $HOME/.seiscomp3/
@ -410,14 +404,14 @@ configuration. Migrate the legacy database parameters and configure the new one:
queues.production.groups = ${defaultGroups}, L1PICK, L1LOCATION
* Set groups per queue in :confval:`queues.$name.groups`,
* **Special case:** Set groups per queue in :confval:`queues.$name.groups`,
ignoring groups in :confval:`defaultGroups`
.. code-block:: properties
queues.production.groups = L1PICK, L1LOCATION, AMPLITUDE, PICK, LOCATION, MAGNITUDE, FOCMECH, EVENT, QC, PUBLICATION, GUI, INVENTORY, ROUTING, CONFIG, LOGGING, IMPORT_GROUP, SERVICE_REQUEST, SERVICE_PROVIDE
* Set groups in :confval:`defaultGroups`
* **Special case:** Set groups in :confval:`defaultGroups`
.. code-block:: properties
@ -426,9 +420,9 @@ configuration. Migrate the legacy database parameters and configure the new one:
.. warning::
When setting groups in the queues all groups configured in
:confval:`defaultGroups` will be ignored unless `${defaultGroups}` is used.
Add all groups from :confval:`defaultGroups` to the queues to keep the
default groups.
:confval:`defaultGroups` will be ignored unless `${defaultGroups}` is
used. Add all groups from :confval:`defaultGroups` to the queues to
keep the default groups.
* Add the interface name, currently only *dbstore* is supported. Example for
a queue names *production*
@ -484,9 +478,8 @@ After adjusting the structure, variables and configuration parameters, check if
Seedlink
--------
When upgrading from SeisComp3 Jakrata-2018.327 or older and using :ref:`seedlink`,
consider the sections :ref:`tutorials_upgrade_seedlink` and
:ref:`tutorials_proc_seedlink`.
When upgrading from SeisComp3 in version Jakrata-2018.327 or older and using
:ref:`seedlink`, consider the section :ref:`tutorials_upgrade_2018.327`.
Automatic module check
@ -508,8 +501,10 @@ modules automatically during computer startup, then the startup script must be
adjusted.
Upgrade From SeisComP3 Jakarta-2018.327 or Before
=================================================
.. _tutorials_upgrade_2018.327:
Upgrading From SeisComP3 <= Jakarta-2018.327
============================================
.. _tutorials_upgrade_seedlink:
@ -591,7 +586,7 @@ Script for renaming the seedlink buffer directories:
net=""
while read a b c; do
case $a in
--) break;;
--) break;;tutorials_upgrade_seedlink
name) eval sta=$c;;
network) eval net=$c;;
esac

4
share/doc/seiscomp/html/_sources/base/tutorials/waveformplayback.rst.txt
View File

@ -77,11 +77,11 @@ Examples:
for your playback.
Example for one hour of data from the GE network from
`FDSNWS at GEOFON <https://geofon.gfz-potsdam.de/waveform/webservices/fdsnws.php>`_:
`FDSNWS at GEOFON <https://geofon.gfz.de/waveform/webservices/fdsnws.php>`_:
.. code-block:: sh
wget -O data.mseed "http://geofon.gfz-potsdam.de/fdsnws/dataselect/1/query?net=GE&cha=BH*&starttime=2021-04-01T06:00:00Z&endtime=2021-04-01T07:00:00Z"
wget -O data.mseed "http://geofon.gfz.de/fdsnws/dataselect/1/query?net=GE&cha=BH*&starttime=2021-04-01T06:00:00Z&endtime=2021-04-01T07:00:00Z"
scmssort -u -E data.mseed > [your miniSEED file]
* **CAPS server:** Extract the data from gempa's CAPS server :cite:p:`caps`

6
share/doc/seiscomp/html/_sources/base/tutorials/waveforms.rst.txt
View File

@ -39,10 +39,10 @@ First, we'll query the upstream Seedlink server,
to confirm that it has current data.
We do this with SeisComP's :program:`slinktool` command,
giving it the '-L' option to list the available stations.
For this example, we'll use the server at host `geofon.gfz-potsdam.de`
For this example, we'll use the server at host `geofon.gfz.de`
on port 18000 (the default) ::
$ slinktool -L geofon.gfz-potsdam.de
$ slinktool -L geofon.gfz.de
AW VNA1 VNA1
AW VNA2 VNA2
[..]
@ -56,7 +56,7 @@ This can be a long list. It shows the network code and station code of each
of the stations for which data is available from this Seedlink server.
We can restrict the output to our station of interest using `grep`. ::
$ slinktool -Q geofon.gfz-potsdam.de | grep GR.CLL
$ slinktool -Q geofon.gfz.de | grep GR.CLL
GR CLL LHN D 2020/05/06 15:13:41.2249 - 2020/05/06 21:15:28.0299
GR CLL BHZ D 2020/05/06 15:13:41.2249 - 2020/05/06 21:22:13.1300
GR CLL BHN D 2020/05/06 15:13:41.2249 - 2020/05/06 21:22:15.4300