You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

344 lines
22 KiB
HTML

<!DOCTYPE html>
<html >
<head>
<meta charset="utf-8" />
<title>Inventory &#8212; SeisComP Release documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/seiscomp.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../../_static/graphviz.css" />
<script type="text/javascript" src="../../_static/seiscomp.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/language_data.js"></script>
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Configuration" href="configuration.html" />
<link rel="prev" title="RecordStream" href="recordstream.html" />
</head>
<body>
<div class="header">
<div class="container">
<div class="brand">
<img class="logo" src="../../_static/brands/seiscomp/text/white.svg"/>
<!-- span class="title">SeisComP Release</span -->
<span class="version">5.3.0</span>
</div>
</div>
</div>
<div class="nav">
<div class="container">
<div class="content"><a class="pull-right" id="sidebar-toggle">TOC</a>
<div class="related" role="navigation" aria-label="related navigation">
<ul>
<li class="right">
<a href="../../genindex.html" title="General Index"
accesskey="I">
index
</a>
</li>
<li class="right">
<a href="configuration.html" title="Configuration"
accesskey="N">
next
</a>
</li>
<li class="right">
<a href="recordstream.html" title="RecordStream"
accesskey="P">
previous
</a>
</li>
<li class="nav-item nav-item-0">
<a href="../../index.html">Home</a>
</li>
<li class="nav-item nav-item-1">
<a href="../concepts.html" accesskey="U">Concepts</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="container">
<div class="fitted content" id="anchors-container">
<div class="body" role="main">
<div class="section" id="inventory">
<span id="concepts-inventory"></span><h1>Inventory<a class="headerlink" href="#inventory" title="Permalink to this headline"></a></h1>
<div class="section" id="scope">
<h2>Scope<a class="headerlink" href="#scope" title="Permalink to this headline"></a></h2>
<p>This chapter describes the concept of inventories.</p>
</div>
<div class="section" id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h2>
<p>In <cite>SeisComP</cite> the term <a class="reference internal" href="../glossary.html#term-inventory"><span class="xref std std-term">inventory</span></a> refers to the meta data of data recording
stations.
Many <cite>SeisComP</cite> applications require inventory information to operate correctly.
The inventory will be read from the <a class="reference internal" href="database.html#concepts-database"><span class="std std-ref">database</span></a>
by default. To insert or update the inventory in the database, this information
needs to be created or downloaded and converted. The following sections will
describe the process of populating the database and how applications get access
to it. All <cite>SeisComP</cite> applications work the the internal inventory format also
known as <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a>.</p>
<p>The inventory shall contain all meta data describing the full recording system
and the
pre-processing of the raw data stream provided to the data processing modules
using the <a class="reference internal" href="recordstream.html#concepts-recordstream"><span class="std std-ref">RecordStream</span></a>. Inventories should be
always complete w.r.t the
processed data streams, correct and up-to-date. Beside network, station, location
and stream information they must include the full sensor and datalogger responses.</p>
<p>Older version used key files to configure available networks and stations.
Because the support of response meta-data was very limited, tools were build to
add this functionality. Since the release of Seattle the concept of key files
for station meta-data has been completely removed from the system. Now <cite>SeisComP</cite>
only handles station meta-data in its own XML format called <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a>.
The task of supporting old key files, dataless SEED and other formats has been
out-sourced to external applications. The inventory synchronization is a
<a class="reference internal" href="#config-fig-inventory-sync"><span class="std std-ref">two-stage process</span></a>:</p>
<ol class="arabic simple">
<li><p>Convert <a class="reference internal" href="#concepts-inventory-format"><span class="std std-ref">external formats</span></a> into <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a></p></li>
<li><p>Synchronize inventory pool with the database: merged all inventory files and
synchronize with the database using <strong class="program">scinv snyc</strong>.</p></li>
</ol>
<div class="figure align-center" id="id4">
<span id="config-fig-inventory-sync"></span><a class="reference internal image-reference" href="../../_images/inventory-sync.png"><img alt="../../_images/inventory-sync.png" src="../../_images/inventory-sync.png" style="width: 12cm;" /></a>
<p class="caption"><span class="caption-text">Inventory synchronization as a two-stage process</span><a class="headerlink" href="#id4" title="Permalink to this image"></a></p>
</div>
<p>All station meta-data are stored in <code class="file docutils literal notranslate"><span class="pre">etc/inventory</span></code>
and can be organized as needed. Either one file per network, a file containing the
complete inventory or one file for all instruments and one file per station.
The update script</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>$ scinv sync
</pre></div>
</div>
<p>loads the existing inventory from the database and merges each file in <code class="file docutils literal notranslate"><span class="pre">etc/inventory</span></code>.
Finally it removes all unreferenced objects and sends all updates to the database.</p>
<p>The <cite>SeisComP</cite> <a class="reference internal" href="modules.html#concepts-modules"><span class="std std-ref">configuration</span></a> does not deal with station meta-data anymore.
It only configures parameters for modules and module-station associations.
The management of the inventory can and should be handled by external tools
e.g. <span id="id1"><em>SMP</em> [<a class="reference internal" href="../references.html#id254" title="SMP. Station Management Portal by gempa GmbH. URL: https://smp.gempa.de/.">21</a>]</span>.</p>
<p>The <cite>SeisComP</cite> documentation describes the
<a class="reference internal" href="../api-python.html#api-datamodel-python"><span class="std std-ref">data model including the inventory</span></a>.</p>
</div>
<div class="section" id="inventory-format">
<span id="concepts-inventory-format"></span><h2>Inventory Format<a class="headerlink" href="#inventory-format" title="Permalink to this headline"></a></h2>
<p>A typical inventory file in <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> looks like this:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;seiscomp</span> <span class="na">xmlns=</span><span class="s">&quot;http://geofon.gfz-potsdam.de/ns/seiscomp-schema/0.11&quot;</span> <span class="na">version=</span><span class="s">&quot;0.11&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;Inventory&gt;</span>
<span class="nt">&lt;sensor&gt;</span>...
<span class="nt">&lt;datalogger&gt;</span>...
<span class="nt">&lt;network&gt;</span>...
<span class="nt">&lt;/Inventory&gt;</span>
<span class="nt">&lt;/seiscomp&gt;</span>
</pre></div>
</div>
<p>The version attribute of the <code class="docutils literal notranslate"><span class="pre">seiscomp</span></code> tag represents the schema version of
the <cite>SeisComP</cite> data model which is consistent with the database schema version
and the version of all other representations.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>All geographic coordinates (latitudes, longitudes, elevation) are assumed in the
World Geodetic System 1984 (WGS84) reference system (National Imagery and
Mapping Agency 2000). Latitudes, longitudes are provided in degrees but
elevations are given in meters.</p>
</div>
<p>Inventories must be provided to <cite>SeisComP</cite> in XML files in <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> format. A
convenient way to generate clean and correct inventory files in <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a>
format is <span id="id2"><em>SMP</em> [<a class="reference internal" href="../references.html#id254" title="SMP. Station Management Portal by gempa GmbH. URL: https://smp.gempa.de/.">21</a>]</span>. Tools are provided to convert between other formats:</p>
<table class="colwidths-given docutils align-left">
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Module namespace</p></th>
<th class="head"><p>Conversion</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>arclink2inv</p></td>
<td><p>Arclink XML to SeisComPML</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../../apps/dlsv2inv.html#dlsv2inv"><span class="std std-ref">dlsv2inv</span></a></p></td>
<td><p>dataless SEED to SeisComPML</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../../apps/inv2dlsv.html#inv2dlsv"><span class="std std-ref">inv2dlsv</span></a></p></td>
<td><p>SeisComPML to dataless SEED</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../../apps/fdsnxml2inv.html#fdsnxml2inv"><span class="std std-ref">fdsnxml2inv</span></a></p></td>
<td><p>FDSN StationXML to SeisComPML and back</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="adding-updating-inventory">
<h2>Adding / Updating Inventory<a class="headerlink" href="#adding-updating-inventory" title="Permalink to this headline"></a></h2>
<p>To add inventory information to the <cite>SeisComP</cite> database one either has to write directly
to the database with custom script (not recommended) or place <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> files
in <code class="file docutils literal notranslate"><span class="pre">&#64;SYSTEMCONFIGDIR&#64;/inventory</span></code>. The service to import all data in that
directory can be called with</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ seiscomp update-config inventory
</pre></div>
</div>
<p>This command runs <a class="reference internal" href="../../apps/scinv.html#scinv"><span class="std std-ref">scinv</span></a> finally. <a class="reference internal" href="../../apps/scinv.html#scinv"><span class="std std-ref">scinv</span></a> merges all XML files and
synchronizes the merged local inventory tree with the database. That is a
rather complex process and for more information it is recommended to study
the source code of <a class="reference internal" href="../../apps/scinv.html#scinv"><span class="std std-ref">scinv</span></a>. The bottom line is that inventory data is created
from <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> files.</p>
<p>Because nobody will ever create such XML files by hand, tools are necessary.
A quite popular tools is the online station management portal (SMP)
<span id="id3">[<a class="reference internal" href="../references.html#id254" title="SMP. Station Management Portal by gempa GmbH. URL: https://smp.gempa.de/.">21</a>]</span>. SMP will output XML in version of <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> directly.</p>
<p>Another source is the FDSN station webservice (FDSNWS). If the <cite>SeisComP</cite>
implementation of FDSNWS is used, the SeisComP XML format can be requested
directly as an extension. Otherwise FDSN StationXML will be provided. Inventory
in FDSN StationXML needs to be converted with either <a class="reference internal" href="../../apps/fdsnxml2inv.html#fdsnxml2inv"><span class="std std-ref">fdsnxml2inv</span></a> or
<a class="reference internal" href="../../apps/import_inv.html#import-inv"><span class="std std-ref">import_inv</span></a>. The latter is a more versatile application that also supports
several import formats.</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ import_inv fdsnxml download-1234.xml
</pre></div>
</div>
<p>This will automatically place the output XML file in
<code class="file docutils literal notranslate"><span class="pre">&#64;SYSTEMCONFIGDIR&#64;/inventory</span></code>. Afterwards call</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ seiscomp update-config inventory
</pre></div>
</div>
<p>to synchronize the changes with the database. If <strong class="program">scconfig</strong> is used,
then either the <code class="docutils literal notranslate"><span class="pre">Sync</span></code> button of the <cite>Inventory</cite> panel or the
<code class="docutils literal notranslate"><span class="pre">Update</span> <span class="pre">configuration</span></code> button of the <code class="docutils literal notranslate"><span class="pre">System</span></code> panel must pressed.</p>
<p><strong>Summary</strong></p>
<p>In order to populate the database with inventory information, the following
steps have to be performed:</p>
<ol class="arabic">
<li><p>Convert existing station meta data formats to <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a></p></li>
<li><p>Place all <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> files at <code class="file docutils literal notranslate"><span class="pre">&#64;SYSTEMCONFIGDIR&#64;/inventory</span></code></p></li>
<li><p>Synchronize the inventory files and write the meta data to the database. Run</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ scinv sync
</pre></div>
</div>
<p>or</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ seiscomp update-config inventory
</pre></div>
</div>
</li>
</ol>
</div>
<div class="section" id="reading-inventory">
<h2>Reading Inventory<a class="headerlink" href="#reading-inventory" title="Permalink to this headline"></a></h2>
<p>Applications usually connect to the database and read the necessary inventory
information. An application can decide whether it requires full response
information including sensor and data logger response functions or just channel
information without instrument descriptions. The latter performs faster and
some applications do not require full instrument information.</p>
<p>An application usually does not require special configuration to read inventory
information. A database connection is enough and it comes usually along with the
handshake message of the messaging server.</p>
<p>If the messaging is not involved, the database can be specified by the
command-line option <code class="docutils literal notranslate"><span class="pre">-d</span></code>:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ myapp -d <span class="o">[</span>type<span class="o">]</span>://<span class="o">[</span>user<span class="o">]</span>:<span class="o">[</span>password<span class="o">]</span>@<span class="o">[</span>host<span class="o">]</span>:<span class="o">[</span>port<span class="o">]</span>
</pre></div>
</div>
<p>There are cases when an application should be run without a database connection
but requires inventory information, particularly in combination with the
<code class="docutils literal notranslate"><span class="pre">--ep</span></code> command line argument. To direct an application to an inventory XML file
(again in <a class="reference internal" href="../glossary.html#term-scml"><span class="xref std std-term">SCML</span></a> format), <code class="docutils literal notranslate"><span class="pre">--inventory-db</span></code> must be used:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ myapp --inventory-db inventory.xml
</pre></div>
</div>
<p>The option <code class="docutils literal notranslate"><span class="pre">--inventory-db</span></code> will cause the module to completely bypass
the database for reading inventory information even if used for event
information. The file <code class="file docutils literal notranslate"><span class="pre">inventory.xml</span></code> can be created from the database
using <a class="reference internal" href="../../apps/scxmldump.html#scxmldump"><span class="std std-ref">scxmldump</span></a>.</p>
</div>
<div class="section" id="related-tools">
<h2>Related Tools<a class="headerlink" href="#related-tools" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p>arclink2inv</p></li>
<li><p><a class="reference internal" href="../../apps/dlsv2inv.html#dlsv2inv"><span class="std std-ref">dlsv2inv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/fdsnxml2inv.html#fdsnxml2inv"><span class="std std-ref">fdsnxml2inv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/import_inv.html#import-inv"><span class="std std-ref">import_inv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/invextr.html#invextr"><span class="std std-ref">invextr</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/inv2dlsv.html#inv2dlsv"><span class="std std-ref">inv2dlsv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/sccnv.html#sccnv"><span class="std std-ref">sccnv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/scinv.html#scinv"><span class="std std-ref">scinv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/scxmldump.html#scxmldump"><span class="std std-ref">scxmldump</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/tab2inv.html#tab2inv"><span class="std std-ref">tab2inv</span></a></p></li>
<li><p><a class="reference internal" href="../../apps/tabinvmodifier.html#tabinvmodifier"><span class="std std-ref">tabinvmodifier</span></a></p></li>
</ul>
</div>
</div>
<div id="anchors-bottom"></div>
</div>
<div class="sidebar" role="navigation" aria-label="main navigation">
<div id="anchors-top"></div>
<div id="anchors" class="content">
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Inventory</a><ul>
<li><a class="reference internal" href="#scope">Scope</a></li>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#inventory-format">Inventory Format</a></li>
<li><a class="reference internal" href="#adding-updating-inventory">Adding / Updating Inventory</a></li>
<li><a class="reference internal" href="#reading-inventory">Reading Inventory</a></li>
<li><a class="reference internal" href="#related-tools">Related Tools</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="recordstream.html"
title="previous chapter">RecordStream</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="configuration.html"
title="next chapter">Configuration</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/base/concepts/inventory.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<div class="container">
<div class="horizontal layout content">
<a class="fade-in" href="https://www.gempa.de" target="_blank">
<img class="brand" src="../../_static/brands/gempa.svg"/>
</a>
<div class="stretched align-center fitted content">
<div>
Version <b>5.3.0</b> Release
</div>
<div class="copyright">
Copyright &copy; gempa GmbH, GFZ Potsdam.
</div>
</div>
<a class="fade-in" href="https://www.gfz-potsdam.de" target="_blank">
<img class="brand" src="../../_static/brands/gfz.svg"/>
</a>
</div>
</div>
</div>
</body>
</html>