Development (#6)

## Added
* 3D fast marching tracer

## Fixed
* fixes for cake ray tracer
* fixes on all fronts

## Docs
*  added documentation



---------

Co-authored-by: Marius Isken <marius.isken@gfz-potsdam.de>

.github/workflows/docs.yaml

@@ -0,0 +1,25 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.10
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install .[dev]
+      - run: mkdocs gh-deploy --force

.pre-commit-config.yaml

@@ -2,23 +2,24 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v4.5.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-added-large-files
+      - id: mixed-line-ending
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    # Ruff version.
+    rev: "v0.1.1"
+    hooks:
+      - id: ruff
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.10.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
         # supported by your project here, or alternatively use
         # pre-commit's default_language_version, see
         # https://pre-commit.com/#top_level-default_language_version
-        # language_version: python3.9
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
-    # Ruff version.
-    rev: "v0.0.287"
-    hooks:
-      - id: ruff
+        # language_version: python3.10

README.md

@@ -3,7 +3,8 @@
 *The friendly earthquake detector*
 
 [![Build and test](https://github.com/miili/lassie-v2/actions/workflows/build.yaml/badge.svg)](https://github.com/miili/lassie-v2/actions/workflows/build.yaml)
-![Python 3.10+](https://img.shields.io/badge/python-3.10-blue.svg)
+[![Documentation](https://img.shields.io/badge/read-documentation-blue)](https://pyrocko.github.io/lassie-v2/)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%203.11-blue.svg)
 <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
 <!-- [![PyPI](https://img.shields.io/pypi/v/lassie)](https://pypi.org/project/lassie/) -->
@@ -26,12 +27,14 @@ Key features are of the earthquake detection and localisation framework are:
 
 Lassie is built on top of [Pyrocko](https://pyrocko.org).
 
+For more information check out the documentation at https://pyrocko.github.io/lassie-v2/.
+
 ## Installation
 
+Simple installation from GitHub.
+
 ```sh
-git clone https://github.com/pyrocko/lassie-v2
-cd lassie-v2
-pip3 install .
+pip install git+https://github.com/pyrocko/lassie-v2
 ```
 
 ## Project Initialisation
@@ -47,7 +50,7 @@ Edit the `my-project.json`
 Start the earthquake detection with
 
 ```sh
-lassie run search.json
+lassie search search.json
 ```
 
 ## Packaging

docs/components/image_function.md

@@ -0,0 +1,15 @@
+# Image Function
+
+For image functions this version of Lassie relies heavily on machine learning pickers delivered by [SeisBench](https://github.com/seisbench/seisbench).
+
+## PhaseNet Image Function
+
+!!! abstract "Citation PhaseNet"
+    *Zhu, Weiqiang, and Gregory C. Beroza. "PhaseNet: A Deep-Neural-Network-Based Seismic Arrival Time Picking Method." arXiv preprint arXiv:1803.03211 (2018).*
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.images.phase_net import PhaseNet
+
+print(generate_docs(PhaseNet()))
+```

docs/components/octree.md

@@ -0,0 +1,10 @@
+# Octree
+
+A 3D space is searched for sources of seismic energy. Lassie created an octree structure which is iteratively refined when energy is detected, to focus on the source' location. This speeds up the search and improves the resolution of the localisations.
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.octree import Octree
+
+print(generate_docs(Octree()))
+```

docs/components/ray_tracer.md

@@ -0,0 +1,56 @@
+# Ray Tracers
+
+The calculation of seismic travel times is a cornerstone for the migration and stacking approach. Lassie supports different ray tracers for travel time calculation, which can be adapted for different geological settings.
+
+## Constant Velocity
+
+The constant velocity models is trivial and follows:
+
+$$
+t_{P} = \frac{d}{v_P}
+$$
+
+This module is used for simple use cases and cross-referencing testing.
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.tracers.constant_velocity import ConstantVelocityTracer
+
+print(generate_docs(ConstantVelocityTracer()))
+```
+
+## 1D Layered Model
+
+Calculation of travel times in 1D layered media is based on the [Pyrocko Cake](https://pyrocko.org/docs/current/apps/cake/manual.html#command-line-examples) ray tracer.
+
+![Pyrocko Cake Ray Tracer](https://pyrocko.org/docs/current/_images/cake_plot_example_2.png)
+*Pyrocko Cake 1D ray tracer for travel time calculation in 1D layered media*
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.tracers.cake import CakeTracer
+
+print(generate_docs(CakeTracer(), exclude={'earthmodel': {'raw_file_data'}}))
+```
+
+## 3D Fast Marching
+
+We implement the fast marching method for calculating first arrivals of waves in 3D volumes. Currently three different 3D velocity models are supported:
+
+* [x] Import [NonLinLoc](http://alomax.free.fr/nlloc/) 3D velocity model
+* [x] 1D layered model 🥞
+* [x] Constant velocity, mainly for testing purposes 🥼
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.tracers.fast_marching import FastMarchingTracer
+
+print(generate_docs(FastMarchingTracer()))
+```
+
+### Visualizing 3D Models
+
+For quality check, all 3D velocity models are exported to `vtk/` folder as `.vti` files. Use [ParaView](https://www.paraview.org/) to inspect and explore the velocity models.
+
+![Velocity model FORGE](../images/FORGE-velocity-model.webp)
+*Seismic velocity model of the Utah FORGE testbed site, visualized in ParaView.*

docs/components/seismic_data.md

@@ -0,0 +1,32 @@
+# Seismic Data
+
+## Waveform Data
+
+The seismic can be delivered in MiniSeed or any other format compatible with Pyrocko.
+
+Organize your data in an [SDS structure](https://www.seiscomp.de/doc/base/concepts/waveformarchives.html) or just a single MiniSeed file.
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.waveforms import PyrockoSquirrel
+
+print(generate_docs(PyrockoSquirrel()))
+```
+
+## Meta Data
+
+Meta data is required primarily for station locations and codes.
+
+Supported data formats are:
+
+* [x] [StationXML](https://www.fdsn.org/xml/station/)
+* [x] [Pyrocko Station YAML](https://pyrocko.org/docs/current/formats/yaml.html)
+
+Metadata does not need to include response information for pure detection and localisation. If local magnitudes $M_L$ are extracted response information is required.
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.models.station import Stations
+
+print(generate_docs(Stations()))
+```

docs/components/station_corrections.md

@@ -0,0 +1,10 @@
+# Station Corrections
+
+Station corrections can be extract from previous runs to refine the localisation accuracy. The corrections can also help to improve the semblance find more events in a dataset.
+
+```python exec='on'
+from lassie.utils import generate_docs
+from lassie.models.station import Stations
+
+print(generate_docs(Stations()))
+```

docs/getting_started.md

@@ -0,0 +1,106 @@
+# Getting Started
+
+## Installation
+
+The installation is straight-forward:
+
+```sh title="From GitHub"
+pip install git+https://github.com/pyrocko/lassie-v2
+```
+
+## Running Lassie
+
+The main entry point in the executeable is the `lassie` command. The provided command line interface (CLI) and a JSON config file is all what is needed to run the program.
+
+```bash exec='on' result='ansi' source='above'
+lassie -h
+```
+
+## Initializing a New Project
+
+Once installed you can run the lassie executeable to initialize a new project.
+
+```sh title="Initialize new Project"
+lassie init my-project
+```
+
+Check out the `search.json` config file and add your waveform data and velocity models.
+
+??? abstract "Minimal Configuration Example"
+  Here is a minimal JSON configuration for Lassie
+  ```json
+  {
+    "project_dir": ".",
+    "stations": {
+      "station_xmls": [],
+      "pyrocko_station_yamls": ["search/pyrocko-stations.yaml"],
+    },
+    "data_provider": {
+      "provider": "PyrockoSquirrel",
+      "environment": ".",
+      "waveform_dirs": ["data/"],
+    },
+    "octree": {
+      "location": {
+        "lat": 0.0,
+        "lon": 0.0,
+        "east_shift": 0.0,
+        "north_shift": 0.0,
+        "elevation": 0.0,
+        "depth": 0.0
+      },
+      "size_initial": 2000.0,
+      "size_limit": 500.0,
+      "east_bounds": [
+        -10000.0,
+        10000.0
+      ],
+      "north_bounds": [
+        -10000.0,
+        10000.0
+      ],
+      "depth_bounds": [
+        0.0,
+        20000.0
+      ],
+      "absorbing_boundary": 1000.0
+    },
+    "image_functions": [
+      {
+        "image": "PhaseNet",
+        "model": "ethz",
+        "torch_use_cuda": false,
+        "phase_map": {
+          "P": "constant:P",
+          "S": "constant:S"
+        },
+      }
+    ],
+    "ray_tracers": [
+      {
+      "tracer": "ConstantVelocityTracer",
+      "phase": "constant:P",
+      "velocity": 5000.0
+      }
+    ],
+    "station_corrections": {},
+    "event_features": [],
+    "sampling_rate": 100,
+    "detection_threshold": 0.05,
+    "detection_blinding": "PT2S",
+    "node_split_threshold": 0.9,
+    "window_length": "PT300S",
+    "n_threads_parstack": 0,
+    "n_threads_argmax": 4,
+  }
+  ```
+
+For more details and information about the component, head over to [details of the modules](components/seismic_data.md).
+
+## Starting the Search
+
+Once happy, start the lassie CLI.
+
+```sh title="Start earthquake detection"
+lassie search search.json
+```

docs/index.md

@@ -1,17 +1,36 @@
-# Welcome to MkDocs
+# Welcome to Lassie 🐕‍🦺
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+Lassie is an earthquake detection and localisation framework. It combines modern **machine learning phase detection and robust migration and stacking techniques**.
 
-## Commands
+The detector is leveraging [Pyrocko](https://pyrocko.org) and [SeisBench](https://github.com/seisbench/seisbench), it is highly-performant and can search massive data sets for seismic activity efficiently.
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+!!! abstract "Citation"
+    TDB
 
-## Project layout
+![Reykjanes detections](images/reykjanes-demo.webp)
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+*Seismic swarm activity at Iceland, Reykjanes Peninsula during a 2020 unrest. 15,000+ earthquakes detected, outlining a dike intrusion, preceeding the 2021 Fagradasfjall eruption. Visualized in [Pyrocko Sparrow](https://pyrocko.org).*
+
+## Features
+
+* [x] Earthquake phase detection using machine-learning pickers from [SeisBench](https://github.com/seisbench/seisbench)
+* [x] Octree localisation approach for efficient and accurate search
+* [x] Different velocity models:
+    * [x] Constant velocity
+    * [x] 1D Layered velocity model
+    * [x] 3D fast-marching velocity model (NonLinLoc compatible)
+* [x] Extraction of earthquake event features:
+    * [x] Local magnitudes
+    * [x] Ground motion attributes
+* [x] Automatic extraction of modelled and picked travel times
+* [x] Calculation and application of station corrections / station delay times
+* [ ] Real-time analytics on streaming data (e.g. SeedLink)
+
+
+[Get Started!](getting_started.md){ .md-button }
+
+## Build with
+
+![Pyrocko](https://pyrocko.org/docs/current/_images/pyrocko_shadow.png){ width="100" }
+![SeisBench](https://seisbench.readthedocs.io/en/stable/_images/seisbench_logo_subtitle_outlined.svg){ width="400" padding-right="40" }
+![GFZ](https://www.gfz-potsdam.de/fileadmin/gfz/GFZ.svg){ width="100" }

docs/theme/announce.html

@@ -0,0 +1 @@
+<b>Lassie is in Beta</b> 🧫 <span style="padding-left: 1em;">Please handle with care</span>

docs/theme/main.html

@@ -0,0 +1,6 @@
+{% extends "base.html" %}
+<!-- start announce block -->
+{% block announce %}
+  {% include 'announce.html' ignore missing %}
+{% endblock %}
+<!-- end announce block -->