Update README.md

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