.. _quickStartGuide:

Quick Start Guide
================== 

Dependencies
-------------
The program is shipped as a Docker container and will run on any Docker-compatible operating system where Docker is installed.

- docker
- a license file from OSOP

.. _installation:

Installation
---------------
1. Make sure you have Linux and Docker installed
2. Download the attachment, install.sh, emailed to you by OSOP to the machine where respGen will run
3. From a command line run ::
	
	$ chmod +x install.sh
	$ sudo ./install.sh

4. To generate the license machine-ID OSOP needs to create the license keys, start respgen on each machine where it is expected to run: ::

	$ sudo respgen

5. The license machine-ID will be output to the screen (and the program will quit). E.g., b063a4faa380d0cdf3b395cb09298e0b:

  5.1 Copy all machine-IDs to a spreadsheet

  5.2 Return the spreadsheet to OSOP

6. OSOP will generate the license keys for each computer and email them back to you:

  6.1 Download each key to the corresponding computer to the directory /opt/osop/license/. Make sure it is named "respgen.key"

7. Configure respgen at /opt/osop/respgen/setup.py. Set the appropriate variables (more on this below).

8. Start respgen as in step 4


.. _io:

Input/ Output
--------------
**Input**:
	- RESP-formatted text files - those are the manufacturer's responses of the known and unknown sensor. The RESP file of the unknown sensor is optional
	- miniSEED-formatted binary files - the waveforms collected from side-by-side known and unknown sensors. Your data must be in miniSEED format. If your data is not in miniSEED format, do not worry. There are many converters available from ORFEUS: http://www.orfeus-eu.org/software/waveform_conversions.html
	- Settings from configuration file (/opt/osop/respgen/setup.py) - you should edit it to set the input files and other parameters. For full details see: :ref:`configuration`

	.. note:: Learn how to setup your experiment at :ref:`experimentalSetupGuide`

**Output**:
	- Plots - each stage plots the result of it's work
	- RESP-formatted text file - 'out4.response.restored' - this is the final output of the processing chain. It lives outside the docker container at /opt/osop/respgen/

	.. note:: see also: :ref:`interpretation`


.. _execution:

How to execute the program
----------------------------

1. Edit /opt/osop/respgen/setup.py (see: :ref:`configuration`)

2. Execute the program sequentially:
	
First, enter the docker container: ::

	$ sudo respgen

Then execute the programs one by one: ::

	# view_cohe.exe
	# stage0.exe
	# stage1e.exe
	# stage2.exe
	# stage3.exe
	# stage4.exe

The final output of the processing chain is the file called **out4.response.restored**, produced by stage4.exe. It lives outside the docker container at /opt/osop/respgen/. This is the RESP formatted file containing the instrument response (poles, zeros and gain) of the unknown sensor. 

.. note:: view_cohe.exe is a diagnostic tool and, technically, can be omitted. Still, it is useful to execute it before the run. It calculates and plots the coherence between the inputs and allows the end user to determine which frequencies are restored reliably; coherence should not differ much from 1.0 in reliable points.

For more details see :ref:`dataFlow` & :ref:`backgroundReading`


.. note:: Before you begin processing your own data, we recommend playing with the :ref:`exampleData` to familiarize yourself with respGen.