From 72d6ddb9ecd2e94f1f2dba08ff55ed7ff1c1a469 Mon Sep 17 00:00:00 2001
From: Jean-Baptiste Bayle <j2b.bayle@gmail.com>
Date: Wed, 13 Oct 2021 16:41:55 -0700
Subject: [PATCH] Update README.md
---
README.md | 101 +++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 85 insertions(+), 16 deletions(-)
diff --git a/README.md b/README.md
index 50aa4d5..3cb08e9 100644
--- a/README.md
+++ b/README.md
@@ -2,24 +2,48 @@
Python package package simulating instrumental noises, the propagation of laser beams, the measurements and the on-board processing.
-The HDF5 measurement file has the following structure,
+The default HDF5 measurement file has the following structure,
```
- |- [[[[WIP...]]]]
+ |- ISC beatnote frequency (total, offsets, fluctuations), of shape (N), in Hz
+ | - isc_carrier_offsets
+ | - isc_carrier_fluctuations
+ | - isc_carriers
+ | - isc_usb_offsets
+ | - isc_usb_fluctuations
+ | - isc_usbs
+ |
+ |- ISC DWS measurements (in yaw and pitch), of shape (N), in rad
+ | - isc_dws_phis
+ | - isc_dws_etas
+ |
+ |- Measured pseudo-ranges (MPRs), of shape (N), in s
+ | - mprs
+ |
+ |- TM beatnote frequency (total, offsets, fluctuations), of shape (N), in Hz
+ | - tm_carrier_offsets
+ | - tm_carrier_fluctuations
+ | - tm_carriers
+ | - tm_usb_offsets
+ | - tm_usb_fluctuations
+ | - tm_usbs
+ |
+ |- REF beatnote frequency (total, offsets, fluctuations), of shape (N), in Hz
+ | - ref_carrier_offsets
+ | - ref_carrier_fluctuations
+ | - ref_carriers
+ | - ref_usb_offsets
+ | - ref_usb_fluctuations
+ | - ref_usbs
|
```
-Metadata are saved as attributes of the measurement file.
-
-You can use pre-generated measurement files, or create your own files with custom simulation parameters. Please read carefully this README for more information. Documentation is available as docstring [for instrumental simulation](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/instrument.py) and [for noise generation](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/noises.py).
-
-### Use pre-generated measurement files
+If the `write_all` option is set to `True`, the HDF5 measurement file also contains intermediary simulated quantities. Refer to [`Instrument.write()`](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/instrument.py) for more information.
-In the table below, we list each measurement file automatically generated and available for download. We provide a link to download the measurement file, and a link to quickly visualize its content.
+Metadata are saved as attributes of the measurement file.
-| Name | Description | Measurement file | Figures |
-|------|-------------|------------------|---------|
+Please read carefully this README for more information. Documentation is available as docstring [for instrumental simulation](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/instrument.py), [for noise generation](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/noises.py), [for DSP tools](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/dsp.py), and [for container classes](https://gitlab.in2p3.fr/lisa-simulation/instrument/-/blob/master/lisainstrument/containers.py).
-### Generate a custom measurement file
+### Run a simulation
Make sure that Python 3.7 or newer is available, and install `lisaconstants` and `lisainstrument` using [pip](https://pip.pypa.io/en/stable/),
```
@@ -27,20 +51,65 @@ pip install git+https://gitlab.in2p3.fr/lisa-simulation/python-constants.git
pip install git+https://gitlab.in2p3.fr/lisa-simulation/instrument.git
```
-You can create a new measurement file,
+You can run a simulation by creating an Instrument object and calling `simulate()`.
```python
from lisainstrument import Instrument
-Instrument().write()
+instrument = Instrument()
+instrument.simulate()
+```
+
+You can parametrize the simulation by setting the desired arguments when instantiating your instrument, or by using the convenience methods,
+```python
+instrument = Instrument(aafilter=None, dt=0.25, size=10000)
+instrument.disable_all_noises(but='laser')
+instrument.disable_dopplers()
+instrument.simulate()
+```
+
+Set `keep_all` to `True` to keep in memory intermediary simulated quantities,
+```python
+instrument.simulate(keep_all=True)
```
-You can parametrize the simulation by setting the desired arguments when instantiating your instrument,
+### Write to a measurement file
+
+You can write the results of a simulation to a measurement file (note that `simulate()` will be called before writing to disk if the simulation has not run yet),
+```python
+instrument = Instrument()
+instrument.write()
+```
+
+You can specify a path to the measurement file, and set `write_all` to `True` to save intermediary simulated quantities,
```python
-Instrument(aafilter=0, dt=0.25, size=10000).write()
+instrument.write('my-file.h5', write_all=True)
```
### Plot measurements
-[[[[WIP...]]]]
+Once the simulation has been run, can use convenience methods to plot all beatnote frequency offsets, beatnote frequency fluctuations, beatnote total frequencies, MPRs, or DWS measurements.
+```python
+instrument.plot_offsets()
+instrument.plot_fluctuations()
+instrument.plot_totals()
+instrument.plot_mprs()
+instrument.plot_dws()
+```
+
+You can skip a number of samples at the beginning, and save the figures to disk,
+```python
+instrument.plot_fluctuations(output='my-fluctuations.pdf', skip=500)
+```
+
+To plot quantities for all spacecraft or MOSAs, use the `plot()` method,
+```python
+instrument.isc_carrier_fluctuations.plot(output='my-figure.png', title='ISC Carrier Fluctuations')
+```
+or use the usual Matplotlib functions with a single timeseries,
+```python
+import matplotlib.pyplot as plt
+plt.plot(instrument.t, instrument.isc_carrier_fluctuations['12'])
+plt.show()
+```
## Contributing
--
GitLab