Add README, license, API docs and fix a few bugs ahead of release

INRIM · Sep 5, 2024 · 249f889 · 249f889
1 parent 84ddce9
commit 249f889
Show file tree

Hide file tree

Showing 13 changed files with 451 additions and 89 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,7 +1,7 @@
 version: 2
 
 build:
-  os: "ubuntu-20.04"
+  os: "ubuntu-22.04"
   tools:
     python: "3.10"
 sphinx:

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Marco Pizzocaro - Istituto Nazionale di Ricerca Metrologica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,109 @@
+# Super-auto-comb
+
+A python script for processing optical comb data useful for Time\&Frequency science in the optical domain.
+The script outputs data in the ROCIT format, useful for comparison using optical fibre links, developed for the [EMPIR project ROCIT](http://empir.npl.co.uk/rocit/) and for the [European Partnership on Metrology Project TOCK](https://www.ptb.de/epm2022/tock/home).
+See also:
+- <https://github.com/INRIM/tintervals>
+- <https://github.com/INRIM/optical-link-data-format>
+
+Development is at 
+- <https://github.com/INRIM/super-auto-comb>
+
+Documentation is available at <https://super-auto-comb.readthedocs.io>
+
+This package is not yet on Pypi.
+
+## Requirements
+This project is managed by Poetry and requirements can be found in the `pyproject.toml` file.
+
+
+## Basic usage
+Install using pipx directly from Github:
+
+`$ pipx install git+https://github.com/INRIM/super-auto-comb.git`
+
+Verify the installation and the available Command Line Interface (CLI) arguments with:
+
+`$ super-auto-comb --help`
+
+To simplify the inputs of CLI arguments, prepare a `super-auto-comb.txt` file in the folder where you want to process comb data similar to:
+
+    do = [my_do1, my_do2]
+    start = 2023-02-24
+    stop = 2023-04-29
+    dir = ./Outputs
+    fig-dir = ./Outputs/Figures
+    comb-dir = your-path-to-comb-data
+    setup-dir = your-path-to-comb-setup-files
+
+and invoke `$ super-auto-comb` to process the data.
+
+For repeating data processing day-after-day you can run `$ super-auto-comb --auto` to process the data.
+The appropriate start date will be read/saved in the file `super-auto-last.txt` for subsequent use. 
+
+## Tracking comb setups
+
+Super-auto-combs read files  that describe designed oscillators (DO) and combs, and how these setups change dover time. For both DOs and combs information are stored line by line. Each line should start with a datetime in ISO format (e.g., `2021-10-28T16:20:21`, local time is ok). It is intended that the data on the line applies from that date to the date on the next line (if any). Changes should be tracked by adding more lines. See the `tests/samples` folder for examples. If super-auto-comb is invoked by `super-auto-comb --do my_do`, it will look for a file `my_do.dat`. If this file has `my_comb` under the `comb` column, super-auto-comb will then look for a `my_comb.dat` file.
+
+### Comb files
+The columns of these files should be:
+
+| Column name | Data type | Description |
+|-------------|-----------|-------------|
+| datetime    | ISO       | Datetime of the change | 
+| maser       | string    | Reference maser |
+| frep        | float     | Repetition rate in Hz |
+| f0          | float     | Offset frequency in Hz (with sign) |
+| counter_f0  | int       | Counter channel counting f0 | 
+
+### Designed oscillators files
+
+DO files are more complex, and should contain all information required to transform from counted frequencies to absolute frequencies, supplemented  by the details of the measurement on the counter (divided in counter1 and counter2 for double counting)
+
+
+| Column name | Data type | Description |
+|-------------|-----------|-------------|
+| datetime    | ISO       | Datetime of the change |
+| comb        | string    | Comb used for the measurement `comb1` or `comb2`    | 
+| physical    | string    | Physical oscillator    |
+| nominal     | string    | Nominal frequency in Hz (should be a string in quotes, e.g. `'518_295_836_590_863.6'`)|
+| kscale      | float     | Frequency scaling (typically 1, 2 in case of SHG) |
+| foffset     | float     | Offset frequency in Hz from the counted beatnote |
+| N           | int       | comb tooth |
+| fbeat_sign  | int       | sign of the physical beatnote |
+| f0_scale    | int       | scaling of f0 (typically 1, 2 for measurements with visible branch) |
+| counter1    | int       | Counter channel |
+| flo1        | float     | Local oscillator frequency in Hz (with sign)) |
+| min1        | float     | Minimum acceptable counted frequency |
+| max1        | float     | Maximum acceptable counted frequency |
+| counter2    | int       | Counter channel |
+| flo2        | float     | Local oscillator frequency in Hz (with sign)) |
+| min2        | float     | Minimum acceptable counted frequency |
+| max2        | float     | Maximum acceptable counted frequency |
+
+
+The math is:
+
+- $f_N = f_{rep} N + f_0 \times scale_{f_0}$
+
+- $f_{beat} = sign_{beat} \times |f_{counter} + f_{lo}|$
+
+- $f_{abs} = k_{scale} \times (f_N + f_{beat}) + f_{offset}$
+
+$f_{abs}$ should be close to the nominal frequency.
+If DOs get disconnected, then a line with only the datetime of disconnection can be used.
+
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)
+
+
+## Acknowledgments
+This work has received funding from the European Partnership on Metrology, co-financed by the European Union’s Horizon Europe Research and Innovation Programme and by the Participating States, under grant number 22IEM01 TOCK.
+
+![badge](./docs/source/Acknowledgement%20badge.png)
+
+## Authors
+
+(c) 2023-2024 Marco Pizzocaro - Istituto Nazionale di Ricerca Metrologica (INRIM)
diff --git a/docs/source/Acknowledgement badge.png b/docs/source/Acknowledgement badge.png
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -7,6 +7,108 @@
 
 This is the documentation for Super-auto-comb.
 
+
+Super-auto-comb is a python script for processing optical comb data useful for Time\&Frequency science in the optical domain.
+Super-auto-combs outputs data in the ROCIT format, useful for comparison using optical fibre links, developed for the [EMPIR project ROCIT](http://empir.npl.co.uk/rocit/) and for the [European Partnership on Metrology Project TOCK](https://www.ptb.de/epm2022/tock/home).
+See also:
+- <https://github.com/INRIM/tintervals>
+- <https://github.com/INRIM/optical-link-data-format>
+
+Development is at 
+- <https://github.com/INRIM/super-auto-comb>
+
+
+This package is not yet on Pypi.
+
+
+## Basic usage
+Install using pipx directly from Github:
+
+`$ pipx install git+https://github.com/INRIM/super-auto-comb.git`
+
+Verify the installation and the available Command Line Interface (CLI) arguments with:
+
+`$ super-auto-comb --help`
+
+To simplify the inputs of CLI arguments, prepare a `super-auto-comb.txt` file in the folder where you want to process comb data similar to:
+
+    do = [my_do1, my_do2]
+    start = 2023-02-24
+    stop = 2023-04-29
+    dir = ./Outputs
+    fig-dir = ./Outputs/Figures
+    comb-dir = your-path-to-comb-data
+    setup-dir = your-path-to-comb-setup-files
+
+and invoke `$ super-auto-comb` to process the data.
+
+For repeating data processing day-after-day you can run `$ super-auto-comb --auto` to process the data.
+The appropriate start date will be read/saved in the file `super-auto-last.txt` for subsequent use. 
+
+## Tracking comb setups
+
+Super-auto-comb read files  that describe designed oscillators (DO) and combs, and how these setups change dover time. For both DOs and combs information are stored line by line. Each line should start with a datetime in ISO format (e.g., `2021-10-28T16:20:21`, local time is ok). It is intended that the data on the line applies from that date to the date on the next line (if any). Changes should be tracked by adding more lines. See the `tests/samples` folder for examples. If super-auto-comb is invoked by `super-auto-comb --do my_do`, it will look for a file `my_do.dat`. If this file has `my_comb` under the `comb` column, super-auto-comb will then look for a `my_comb.dat` file.
+
+### Comb files
+The columns of these files should be:
+
+| Column name | Data type | Description |
+|-------------|-----------|-------------|
+| datetime    | ISO       | Datetime of the change | 
+| maser       | string    | Reference maser |
+| frep        | float     | Repetition rate in Hz |
+| f0          | float     | Offset frequency in Hz (with sign) |
+| counter_f0  | int       | Counter channel counting f0 | 
+
+### Designed oscillators files
+
+DO files are more complex, and should contain all information required to transform from counted frequencies to absolute frequencies, supplemented  by the details of the measurement on the counter (divided in counter1 and counter2 for double counting)
+
+
+| Column name | Data type | Description |
+|-------------|-----------|-------------|
+| datetime    | ISO       | Datetime of the change |
+| comb        | string    | Comb used for the measurement `comb1` or `comb2`    | 
+| physical    | string    | Physical oscillator    |
+| nominal     | string    | Nominal frequency in Hz (should be a string in quotes, e.g. `'518_295_836_590_863.6'`)|
+| kscale      | float     | Frequency scaling (typically 1, 2 in case of SHG) |
+| foffset     | float     | Offset frequency in Hz from the counted beatnote |
+| N           | int       | comb tooth |
+| fbeat_sign  | int       | sign of the physical beatnote |
+| f0_scale    | int       | scaling of f0 (typically 1, 2 for measurements with visible branch) |
+| counter1    | int       | Counter channel |
+| flo1        | float     | Local oscillator frequency in Hz (with sign)) |
+| min1        | float     | Minimum acceptable counted frequency |
+| max1        | float     | Maximum acceptable counted frequency |
+| counter2    | int       | Counter channel |
+| flo2        | float     | Local oscillator frequency in Hz (with sign)) |
+| min2        | float     | Minimum acceptable counted frequency |
+| max2        | float     | Maximum acceptable counted frequency |
+
+
+The math is:
+
+- $f_N = f_{rep} N + f_0 \times scale_{f_0}$
+
+- $f_{beat} = sign_{beat} \times |f_{counter} + f_{lo}|$
+
+- $f_{abs} = k_{scale} \times (f_N + f_{beat}) + f_{offset}$
+
+$f_{abs}$ should be close to the nominal frequency.
+If DOs get disconnected, then a line with only the datetime of disconnection can be used.
+
+
+## Acknowledgments
+This work has received funding from the European Partnership on Metrology, co-financed by the European Union’s Horizon Europe Research and Innovation Programme and by the Participating States, under grant number 22IEM01 TOCK.
+
+![badge](./Acknowledgement%20badge.png)
+
+## Authors
+
+(c) 2023-2024 Marco Pizzocaro - Istituto Nazionale di Ricerca Metrologica (INRIM)
+
+
+
 ```{toctree}
 :caption: 'Contents:'
 :maxdepth: 2

diff --git a/src/super_auto_comb/calc.py b/src/super_auto_comb/calc.py
@@ -3,9 +3,35 @@
 import numpy as np
 
 
-def beat2y(
-    f_beat, nominal, N, f_rep, f0, f_beat_sign=1, k_scale=1, f0_scale=1, f_offset=0.0
-):
+def beat2y(f_beat, nominal, N, f_rep, f0, f_beat_sign=1, k_scale=1, f0_scale=1, f_offset=0.0):
+    """Calculate the fractional frequency y from beatnote values, using arbitrary precision numbers where appropriate.
+
+    Parameters
+    ----------
+    f_beat : ndarray of floats
+        Input frequency beat, unsigned
+    nominal : str
+        Nominal frequency in Hz as string.
+    N : int
+        Comb tooth number
+    f_rep : float
+        Comb repetition rate in Hz
+    f0 : float
+        Comb offset frequency in Hz
+    f_beat_sign : int, optional
+        Sign of f_beat, by default 1
+    k_scale : int, optional
+        Frequency scaling (typically 1, 2 in case of SHG), by default 1
+    f0_scale : int, optional
+        Frequency scaling of f0 (typically 1, 2 for measurements with visible branch), by default 1
+    f_offset : float, optional
+        Offset frequency in Hz from the counted beatnote, by default 0.0
+
+    Returns
+    -------
+    ndarray
+        Fractional frequency y
+    """
     # ensure type where appropriate
     df_nom = decimal.Decimal(nominal.strip("'"))
     N = int(N)

diff --git a/src/super_auto_comb/cli.py b/src/super_auto_comb/cli.py
@@ -35,6 +35,7 @@
 
 
 def parse_args(args):
+    """Utility for Configargparse arguments."""
     # fmt: off
 
     parser = configargparse.ArgumentParser(description='Process Comb data files.', formatter_class=configargparse.ArgumentDefaultsHelpFormatter, default_config_files=['./super-auto-comb.txt']) 
@@ -83,6 +84,7 @@ def parse_args(args):
 
 
 def cli():
+    """CLI entry point. Parse arguments from sys and launch the main script if necessary."""
     args = parse_args(sys.argv[1:])
 
     if not os.path.exists(args.dir):
@@ -96,6 +98,7 @@ def cli():
 
 
 def main(args):
+    """Main script for processign comb data."""
     if args.auto:
         try:
             auto_list = np.loadtxt(args.auto_file, dtype=str)
@@ -262,8 +265,8 @@ def main(args):
                         mask4 = deglitch_from_median_filter(
                             f_beat,
                             premask=tmask,
-                            median_window=args.median_window,
-                            median_threshold=args.median_threshold,
+                            median_window=args.median_filter_window,
+                            median_threshold=args.median_filter_threshold,
                         )
                         tmask = mask1 & mask2 & mask3 & mask4
                     else: