MS_GENFACTMULT(3)

💖 MS_GENFACTMULT — generate SEED sample rate factor and multiplier 💖

okay bestie, welcome to the <libmseed.h> corner of the library, this page lives in section 3 (library functions, iykyk) and it's literally about turning a lil sample rate into the exact pair of numbers SEED headers are obsessed with. let's go 🦋

✨ SYNOPSIS ✨

#include <libmseed.h>

int  ms_genfactmult ( double samprate, int16_t *factor,
                      int16_t *multiplier );

int  ms_ratapprox ( double real, int *num, int *den,
                    int maxval, double precision );

🌸 DESCRIPTION 🌸

so ms_genfactmult is the main character here: it generates an appropriate SEED sample rate factor and multiplier pair from a double precision sample rate. periodt. 💅

and here's the vibe check on samprate: if it's positive it's expected to represent a rate in samples/second, but if it's negative it's expected to represent a period in seconds/sample. yes, the sign is doing the talking. 🙈

non-integer sample rates and periods are supported between 32767.0 and 1/32767.0. and if you try to hand it a non-integer rate or period outside that range? nope. an error will be returned. not me getting rejected by the range check 😭

integer sample rates and periods are supported between 1 and the maximum possible value (32767 * 32767). values from 1 to 32767 are represented directly, super simple, no drama. values larger than 32767 get factored, and they're represented exactly when possible and approximated otherwise — and the discrepancy becomes larger as the values reach the maximum possible value. so like, the closer you get to the limit, the more it's giving "close enough ✨". highkey important to know.

and why are factor and multiplier int16_t?? because that is the integer size needed for the fixed section of the SEED data header. the format said 16 bits and the format got 16 bits. iconic behavior tbh. 👑

now, ms_ratapprox is the supporting character that eats every single time: it finds an approximate rational number for a real through continued fraction expansion. given a double precision real, the routine tries to find a rational in numerator (num) and denominator (den) form whose absolute values are not larger than maxval while trying to reach a specified precision. chef's kiss, math girlies rise 🧚

⭐ RETURN VALUES ⭐

• ms_genfactmult — returns 0 on success, and -1 when the value is outside of the supported range or on error. so like, zero is the slay, negative one is the "we don't know her". 💀
• ms_ratapprox — returns the number of iterations performed. that's it, that's the tea. 🍓

🎀 AUTHOR 🎀

Chad Trabant IRIS Data Management Center

reminder bestie: the factor/multiplier pair is int16_t because the SEED fixed header demands it, and out-of-range non-integer rates/periods are a hard error, not a vibe. do not test that boundary unless you enjoy -1. 🙈

okay that's the whole page, you understood it perfectly, I'm so proud of you 🫶✨ this was Libmseed API, dated 2016/10/07, and it's the MS_GENFACTMULT(3) manual page — now go generate some factors and multipliers, you've got this 💖🌈