Handling optical link data

tintervals.rocitlinks provides a structure to handle frequency data in the format established in the EMPIR project ROCIT.

The package can handle data in fractional frequency or transfer beat notation based on the math in Lodewyck et al., “Universal formalism for data sharing and processing in clock comparison networks”, Phys. Rev. Research 2, 043269 (2020).

Basic usage

import tintervals.rocitlinks as rl

# load link data
link1 = rl.load_link_from_dir('./Data/Link1', meta='metadata.yml')
link2 = rl.load_link_from_dir('./Data/Link2', meta='metadata.yml')

# chaining link
reslink, masks = rl.chain(link1, link2)

# averaging links
days, daylink, dcount = rl.link_average(reslink, 'day')

# saving resulting link
rl.save_link_to_dir('./Output', daylink)

Module documentation

Classes:

`Oscillator`([name, v0, description, ...])	A simple class to store oscillator informations.
`Link`([data, r0, oscA, oscB, sB, name, step])	The main class for handling link data.

Functions:

`chain2`(link1, link2)	Chain 2 links in sequence.
`chain`(*links)	Chain multiple links in sequence.
`average`(link, intervals)	Average a link in given intervals
`link_average`(link[, base, offset, ...])	Average a link in regular intervals.
`save_link_to_dir`(dir, link[, extra_names, ...])	Save Link data to a directory.
`load_link_from_dir`(dir[, meta, start, stop, ...])	Load link data from a directory.
`load_links_from_osc_names`(link_dos[, dir])	Loads a chain of links from oscillators names.

class tintervals.rocitlinks.Oscillator(name='', v0=0.0, description='', grs_correction=0.0, systematic_uncertainty=0.0)

A simple class to store oscillator informations.

name

Name of the oscillator

Type:: str

v0

Nominal frequency (could be zero)

Type:: decimal.Decimal

description

Description of the oscillator (if any)

Type:: str

grs_correction

If the oscillator is a clock, gravitational redshift still to be applied to the clock (if any)

Type:: float

systematic_uncertainty

If the oscillator is a clock, systematic uncertainty of the clock (if any)

Type:: float

class tintervals.rocitlinks.Link(data=array([], dtype=float64), r0=None, oscA=None, oscB=None, sB=None, name=None, step=1.0)

The main class for handling link data.

Parameters:

data (ndarray, optional) – data of the link (with columns timetags, comparator, flag), by default np.empty(0)
r0 (decimal.Decimal, optional) – Nominal ratio, by default ratio of oscillator nominal frequencies (if any) or zero
oscA (Oscillator, optional) – Oscillator A (denominator), by default None
oscB (Oscillator, optional) – Oscillator B (numerator), by default None
sB (float, optional) – Scaling factor, by default oscB nominal frequency (if any) else 1
name (string, optional) – Name of the link, by default None
step (float, optional) – Time step of the data, by default 1.

Methods:

`normalize`([new_r0])	Renormalize link data to a new r0
`drop_invalid`([drop_flag])	Remove invalid points
`extend`([start, stop])	Fill in missing timetags with invalid data.
`copy`()	Return a copy of the object.
`average`([base, offset, drop_flag, ...])	Reduce the link averaging data in place.

normalize(new_r0=None)

Renormalize link data to a new r0

Parameters:: new_r0 (deciaml.Decimal, optional) – explicit new ratio for the normalization, by default None. If none, the link is renormalized to the ratio of oscillators nominal frequencies (if any).

Notes

It requires that the nominal frequency of OscA is set, and either new_r0 or the nominal frequeny of oscB set.

drop_invalid(drop_flag=0)

Remove invalid points

Parameters:: drop_flag (int or float, optional) – drop point whose flag is < drop_flag, by default 0

extend(start=None, stop=None)

Fill in missing timetags with invalid data.

Parameters:

start (float, optional) – start point of the extension, by default the minimum timetag
stop (float, optional) – stop point of the extension, by default the maximum timetag
np.arange(start (Timetags are filled in the)
stop
link.step).
zero. (Inserted data has delta and flag)

copy(): Return a copy of the object.

average(base=1.0, offset=0.0, drop_flag=0, timetags_as_start=True, **kwargs)

Reduce the link averaging data in place.

Parameters:

base (float, optional) – Time base of average (average data every base seconds), by default 1.
offset (float, optional) – offset in the time base (if zero, multiple of base are used), by default 0.
drop_flag (int or float, optional) – drop point whose flag is < drop_flag, by default 0
timetags_as_start (bool, optional) – If true, new timetags are the start of the averaging intervals; if false, the center, by default True
**kwargs – other keyword arguments passed to link_average

Notes

Method base on the function link_average.

tintervals.rocitlinks.chain2(link1, link2)

Chain 2 links in sequence.

Parameters:

link1 (link B/A) – link object to be chained.
link2 (link C/B) – link object to be chained.

Returns:

res – chained link object C/A.
mask1 – mask to be applied to link1 to select timetags common to link2
mask2 – mask to be applied to link2 to select timetags common to link1

tintervals.rocitlinks.chain(*links)

Chain multiple links in sequence.

Parameters:

*links – link objects to be chained.

Returns:

res – chained link object.
masks – list of masks to select timetags in the common uptime (one for each link).

tintervals.rocitlinks.average(link, intervals)

Average a link in given intervals

Parameters:

link (Link) – link object to be averaged.
intervals (str or 2d arrays) – One of ‘hour’,’day’ or ‘bipm’ to average every hour, day or BIPM 5-day intervals. Or a 2d-array of start-stop intervals.

Returns:

vals – start/stop intervals of the averages.
res – averaged link data (all columns, so average timetag, average delta and average flag).
count – number of averaged point for each intervals.

Notes

Based on tintervals.maverage.

tintervals.rocitlinks.link_average(link, base=1.0, offset=0.0, drop_flag=0, timetags_as_start=True, **kwargs)

Average a link in regular intervals.

Parameters:

link (Link) – link object to be averaged
base (float, optional) – Time base of average (average data every base seconds), by default 1.
offset (float, optional) – offset in the time base (if zero, multiple of base are used), by default 0.
drop_flag (int or float, optional) – drop point whose flag is < drop_flag, by default 0
timetags_as_start (bool, optional) – If true, new timetags are the start of the averaging intervals; if false, the center, by default True

Returns:

vals – start/stop intervals of the averages.
res – averaged link object.
count – number of averaged point for each intervals.

tintervals.rocitlinks.save_link_to_dir(dir, link, extra_names=[], message='', time_format='mjd', yfmt='{:.10e}')

Save Link data to a directory.

Parameters:

dir (string) – ouput directory
link (Link) – link to be saved
extra_names (list, optional) – if Link data has more than 3 columns, this can be used to specify their name, by default []
message (str, optional) – message to be written in the header, by default ‘’
time_format (['mjd', 'iso', 'unix'], optional) – Specify ouput time format, by default ‘mjd’
digits (int, optional) – Number of digits for the Link delta, by default 10

Notes

Data is saved in separate files, one file for each day. Link metadata is saved in a yaml file in the directory.

tintervals.rocitlinks.load_link_from_dir(dir, meta=None, start=None, stop=None, discard_invalid=True, time_format='mjd', ext=['.dat', '.txt'], round=True, remove_not_unique=True, verbose=False, **kwargs)

Load link data from a directory.

Parameters:

dir (str) – Directory to be read
meta (str) – yaml file with metadata, by default search for a yaml file with the same name of dir.
start (float) – if given, crop the data from this point, by default None
stop (float) – if given, crop the data to this point, by default None
discard_invalid (bool, optional) – if True, discard data with flag=0, by default True
time_format (str, optional) – Specify input time format, ‘mjd’, ‘iso’ or ‘unix’, by default ‘mjd’
ext (list or string, optional) – extension of the file to read, by default [‘.dat’,’.txt’]
round (bool, optional) – if True, round timetags to the nearest second, by default True
remove_not_unique (bool, optional) – if True, remove data corresponding to not-unique timetags, by default True
verbose (bool, optional) – if True, verbose ouput
**kwargs – other keyword argument to pass to np.genfromtxt

Returns:

Link object with data from the directory.

Return type:

Link

tintervals.rocitlinks.load_links_from_osc_names(link_dos, dir='.', **kwargs)

Loads a chain of links from oscillators names.

Parameters:

link_dos (list of strings) – names of the oscillators to be chained
dir (str, optional) – directory to be read, by default ‘.’
**kwargs – other keyword arguments as in load_link_from_dir

Returns:

loaded data

Return type:

list of Link objects

Notes

Loads a chain of links whose names are in the form OscA-OscB. For example:

>>> load_links_from_osc_names(['A', 'B', 'C', 'D'])

would load directories ‘B-A’, ‘C-B’ and ‘D-C’ (or load and invert the links from directories ‘A-B’, ‘B-C’ and ‘C-D’).