.. _catalyst-sec-configuration:

Setup and configuration
=======================

|package| is configured in three places:

* the module configuration :file:`catalyst.cfg`, for settings that belong to
  the installation (database, messaging, plugins, file paths, limits),
* :ref:`processing profiles <catalyst-sec-profiles>`, for the processing
  settings of the GUI, typically one per network or region,
* the GUI itself, where every processing setting can be changed at runtime.

The module configuration is read from
:file:`@DEFAULTCONFIGDIR@/catalyst.cfg`,
:file:`@SYSTEMCONFIGDIR@/catalyst.cfg` and :file:`@CONFIGDIR@/catalyst.cfg`,
in this order, as for every |scname| module. Use :program:`scconfig` or edit
the files directly. All parameters are listed in the
:ref:`module reference <catalyst>`.


Starting Catalyst
-----------------

|appname| is a |scname| GUI application and accepts the usual command-line
options. Typical calls:

* Work on files only, without database or messaging:

  .. code-block:: sh

     catalyst

  Open an XML file with **File → Open…**.

* Load from the database:

  .. code-block:: sh

     catalyst -d mysql://sysop:sysop@localhost/seiscomp

* Load from the database and send results to the messaging system:

  .. code-block:: sh

     catalyst -H localhost -d mysql://sysop:sysop@localhost/seiscomp

Without a messaging connection, **File → Send Selection to Messaging** and
**Review in scolv** are not available.


Plugins
-------

The origin score uses the OriginMultiFeature score processor of
:program:`scevent`, which is provided by the ``scoremf`` plugin. Load it and
configure its parameters in :file:`catalyst.cfg`:

.. code-block:: properties

   plugins = ${plugins}, scoremf

   # Which score processor to use and whose score.* configuration to read.
   score.processor = OriginMultiFeature
   score.configModule = scevent

``score.processor`` and ``score.configModule`` are optional and default to the
values shown. With ``score.configModule = scevent`` the score uses the same
``score.mf.*`` parameters as :program:`scevent`, so |package| and the real-time
system rank origins the same way.

If the plugin cannot be loaded, the score shows N/A. **Calculate score**
retries and reports the reason.


Processing limits
-----------------

.. code-block:: properties

   # Minimum number of phases a located origin needs (default 5).
   # Values below 4 are raised to 4.
   minPhases = 5

   # Upper limit on the number of origins nucleation may create, as a guard
   # against runaway output. 0 = no limit.
   maxOrigins = 5000

``maxOrigins`` is not shown in the GUI on purpose.


Over-detecting stations
-----------------------

Picks from stations that produce many more picks than the others are weak
evidence. They are used by the *Clean Q* metric and the isolated-pick filter.
Stations are treated as over-detecting either because they are listed
explicitly, or, without a list, because they have more than ``factor`` times
the median number of picks per station in the loaded data.

.. code-block:: properties

   # Explicit list: NET.STA or a plain station code.
   qc.overdetection.stations = IS.HRAUN, KRA

   # Automatic detection when no list is given. 0 or less switches it off.
   qc.overdetection.factor = 3.0


3D view
-------

.. code-block:: properties

   # Reference cities shown in the 3D view. A "cities" key in the processing
   # profile overrides this list.
   cities = Reykjavik, Akureyri

   # SeisComP cities XML used to look up their coordinates.
   # Default: @DATADIR@/cities.xml
   citiesFile = @DATADIR@/cities.xml

   # Folder with the GEBCO elevation tiles used for topography.
   demPath = /home/data/elevation

   # Total number of points used to draw fault surfaces (default 500000).
   faultPointBudget = 500000


Travel-time models
------------------

The **TTT model** list offers the tables configured for the chosen travel-time
interface:

.. code-block:: properties

   ttt.LOCSAT.tables = iasp91, sil
   ttt.libtau.tables = iasp91, ak135

For LOCSAT, the profiles of the LOCSAT locator are used if
``ttt.LOCSAT.tables`` is not set.


Processing profiles
-------------------

Profiles are declared in :file:`catalyst.cfg` as well. See
:ref:`processing profiles <catalyst-sec-profiles>`.

.. code-block:: properties

   profiles = iceland, ukraine
   defaultProfile = iceland
   profile.iceland.configFile = @SYSTEMCONFIGDIR@/iceland.profile
   profile.ukraine.configFile = @SYSTEMCONFIGDIR@/ukraine.profile


Window layout
-------------

The panel layout is saved when |appname| closes and restored at the next
start. **View → Home (reset layout)** returns to the default layout, and
**View → Panels** shows or hides individual panels.