CalibDataFrame — the corpus API

The corpus specifies what measured data looks like and where it comes from. This is the object that implements it.

CalibDataFrame is that corpus. It is a deliberately thin wrapper composing a pandas.DataFrame (exposed as .df) — it does not reimplement the frame. It adds only the two things a raw frame lacks for this job:

• a per-row measured_at timestamp, stamped automatically on add_datapoint, so the corpus records when each measurement was taken;
• a storage path — save / load to CSV — so the corpus is a committed artifact.

Everything else is native pandas on .df.

Building and using a corpus

from waveflow.calib import CalibDataFrame

db = CalibDataFrame(columns=["n_row", "n_col", "cycles"])    # declare a column order (optional)
db.add_datapoint({"n_row": 1, "n_col": 64,  "cycles": 128})  # one cosim run; stamped measured_at
db.add_datapoint({"n_row": 4, "n_col": 64,  "cycles": 655})
db.extend([                                                  # or add several at once
    {"n_row": 4, "n_col": 256, "cycles": 2383},
    {"n_row": 8, "n_col": 256, "cycles": 4720},
])

db.df                       # the underlying pandas.DataFrame — filter / select natively
db.df[db.df.n_row == 4]     # e.g. just the 4-row points
db.df["cycles"].max()       # any pandas operation
len(db)                     # number of measurements

member	what it does
CalibDataFrame(columns=None, path=None)	empty corpus; columns fixes display order, path is the default save/load target
add_datapoint(point, *, measured_at=None)	append one row (a column → value mapping), timestamped
extend(points)	append many rows
.df	the underlying pandas.DataFrame (filter / select / display)
len(db)	number of rows
save(path=None)	write the corpus to CSV (uses path or the path set at construction)
CalibDataFrame.load(path)	reload a previously saved corpus

db.save("calib/fir_grid.csv")                 # persist the corpus
db2 = CalibDataFrame.load("calib/fir_grid.csv")

measured_at is metadata, never a feature

The measured_at column is provenance, not a model input. Models select explicit basis / target columns (see the model kinds), so the timestamp can never leak into a fit — there is no “use all columns” path that would sweep it in.

See also

• The corpus — the format this implements, and why it is derived rather than maintained.
• The model kinds — fitting over the corpus’s basis / target columns.
• A worked example — building a corpus and fitting it end-to-end.
• Calibration — the overall workflow this corpus feeds.