Models and formulas

Some values come from others: a cross-section from a width and a thickness, a stress from a force and that cross-section, a modulus fitted over a table's columns. In SampleKit such values are computed by your own Python formulas, gathered in a project's model. This page says what a model is, how SampleKit runs it, and what happens when a formula cannot run.

A model is a Python class

A project names its model in .samplekitrc:

[model]
path = "model/specimen.py"
class = "Specimen"
python = ".venv"

The model is a subclass of samplekit.Sample. Its __init__ declares each property of the project and, for the computed ones, the formula that gives them:

import math

import samplekit as sk

class Specimen(sk.Sample):
    def __init__(self, path=None, name=None):
        super().__init__(path, name=name)
        self.width = sk.Property(unit="mm", value=sk.stats.mean,
                                 uncertainty=sk.stats.standard_error)
        self.thickness = sk.Property(unit="mm", value=sk.stats.mean,
                                     uncertainty=sk.stats.standard_error)
        self.area = sk.Property(unit="mm²", compute=self._area,
                                depends_on=["width", "thickness"])

    def _area(self):
        w, t = self.width, self.thickness
        value = w.value * t.value
        return value, math.hypot(t.value * w.uncertainty, w.value * t.uncertainty)

It is ordinary Python: it can import other files beside it and any package installed in its environment, such as numpy or scipy.

One model per project. The properties and formulas of one kind of sample are rarely those of another, so a project has one model and another kind is another project (Projects). Two projects can share one model file, by pointing path at it.

A project without a model works. Every value is then typed in the files. Reading, filtering, sorting, checking and exporting never need Python; only computing and drawing figures do.

One formula per value

Each computed value has its formula, declared where the value is:

Declaration

The formula gives

sk.Property(compute=f)

the property; f() returns a number, or (value, uncertainty)

sk.Property(compute_value=f)

the value alone, beside an uncertainty given apart

sk.Property(compute_uncertainty=f)

the uncertainty, beside a value you enter or compute apart

sk.Property(value=sk.stats.mean, uncertainty=…)

both, as statistics of the readings (Readings and statistics)

sk.Property(compute=f, depends_on=[…]), as a table's column

the column, one row at a time; f(row) returns a number, or (value, uncertainty)

sk.Property(compute_column=f, depends_on=[…]), as a table's column

the whole column at once; f(columns) returns one cell per row

sk.ComputedColumns([…], compute=f, depends_on=[…]), in a table's computed

several columns at once

Why a formula per value rather than one function computing everything: so that SampleKit can tell which value is out of date, compute only that one, and know which values a changed formula affects. A collection can take hours to compute; recomputing only what is outdated is what makes that bearable.

Write each formula as a method of the class (self._area). A lambda that uses self keeps every sample in memory as long as your script runs.

Formulas over a table

A table's columns are declared with sk.Property, as the sample's properties are, and a column's formula is declared on it in the same words. It can be computed in two ways:

  • Row by row, sk.Property(compute=f, depends_on=["row.force", "area"]): the formula runs once per row, receives the row, can read the sample through self, and returns the cell. Use it when a cell depends only on its own row, and on the sample's properties. compute_value and compute_uncertainty give one number of each cell, as for a property: an instrument rated at 0.5 % of its reading is sk.Property(unit="kN", compute_uncertainty=f, depends_on=["row.force.v"]), the value entered in each row and its uncertainty computed from it.

  • The whole column at once, sk.Property(compute_column=f, depends_on=["curve.force", "curve.strain"]): the formula receives the columns it reads, by name, and returns one cell per row. Use it when a row's value depends on other rows: a slope from one row to the next, the energy absorbed so far.

A formula that fills several columns at once, the two parameters of a fit, is declared on the table, computed=[sk.ComputedColumns(["low", "high"], compute=f, depends_on=[…])], and returns a dict, one cell (or one list of cells, with compute_column=) for each column it fills.

A property can also read a whole column: a fit over a table's rows, the highest stress of a curve. It declares the columns it reads (curve.stress), and a change to any cell of them makes it outdated.

Every formula says what it reads

A computed value declares its inputs, with depends_on:

self.area = sk.Property(unit="mm²", compute=self._area,
                        depends_on=["width", "thickness"])
# or, later in __init__:
self.set_dependencies("area", depends_on=["width", "thickness"])

This is how SampleKit knows that area is outdated when width changes, and in which order to compute: width before area. A model that forgets a declaration is refused before any formula runs, with a message naming the value.

  • A formula that reads nothing of the sample, a constant scale for example, declares depends_on=[].

  • A formula that reads the value beside its own uncertainty names the value channel: depends_on=["gauge_length.v"].

  • A property with two formulas reading different inputs gives one list per part: depends_on={"v": ["width", "thickness"], "u": ["width", "thickness", "area.v"]}.

  • A table's formulas name their inputs in their depends_on ("row.force", "area", "curve.force"), and need no set_dependencies.

SampleKit trusts the declaration. It cannot see what a formula actually reads. If area reads thickness but declares only width, a change to thickness does not make area outdated, and nothing warns you. This is the one rule that no check can enforce for you: declare every value a formula reads.

Where the model runs

The samplekit command line is a program with no Python inside. To compute, it starts a Python interpreter in a separate process, and talks to it:

the Python [model] python names in .samplekitrc: an environment folder, python = ".venv" (its bin/python, or Scripts\python.exe on Windows, so that one file serves both), or an interpreter itself. samplekit init makes the project's .venv/ and writes that line. Nothing is searched for: a .venv/ in a folder above, which belongs to another project or which a colleague's clone would not have, is never used, and a project that declares no interpreter computes nothing and says the line to write.

The SampleKit Python package must be installed there, in the same version as the command line; a different version is refused, naming both. samplekit --show-rc FOLDER prints which configuration, model and Python a command would use.

From a Python script, compute() runs the formulas in the script's own process instead, with the same rules.

Nothing about the model is written into the samples. Which version of each formula computed which value is kept in the project's history, which travels with the project (Current and outdated).

The model's description

Each time Python imports the model, SampleKit writes down what it declares in .samplekit/model.json, beside .samplekitrc: every property with its unit, which ones a formula computes and what each formula reads, which take their value from a statistic of readings, the tables with their columns and the rows the model gives them itself, the attributes and the figures, with a fingerprint of the model's files.

That description is what lets most commands answer without starting Python: status and a state filter list what the model owes each sample, new and set know that a name is one of the model's properties and its unit, list figures names the model's figures, and the TUI marks what is never computed. When you edit the model, the fingerprint no longer matches; the next of those commands starts Python once to describe the model again, and the ones after it start none. A description that no longer matches the model is never used.

You never write or edit this file, and it does not belong in git: it is made again from the model whenever it is needed.

Running without asking

SampleKit runs a project's model without asking, as python runs a script you give it: a model is code you wrote or chose. What it does instead is say what it runs. Every computation begins by naming the model file, and with -v the configuration before it:

model  model/specimen.py

and computing is always in three steps you choose between:

Command

What it does

samplekit FOLDER compute

lists what would run and why, then asks compute these N values? [y/N]

answered y

computes and shows every result, then asks apply these changes? [y/N]

samplekit FOLDER compute --write

computes the values and writes them, asking nothing

Answering n to the second question is how you watch a new or edited model run before it touches a file. The answers are read from the standard input: yes | samplekit FOLDER compute answers both, and a script given no input answers no, writing nothing. In the TUI, C shows what is not current and computes it once you answer y, and c computes the value under the cursor; in Python, compute() then save().

What runs by default is what is not current, in the order the inputs require: values never computed, outdated values, values whose formula changed. -p NAME narrows it to named values and the inputs they need; --rerun adds the current ones; --force adds the values typed by hand over their formula (Current and outdated).

An interrupted run loses only the value in progress: Ctrl+C stops it, and every value finished before is written, those of the sample under way among them. The next compute starts from what is still not current.

When a formula cannot run

A missing input: the value waits

If an input is absent, nobody entered it yet, the formula is not run and the value waits: area · waits for thickness. This is not a failure. It is the normal state of a sample halfway through its measurements; once you enter thickness, the next compute runs area. A waiting value does not fail status --exit-code.

If an input is n/a, the question does not apply, and the value is n/a too, without running the formula (Values and uncertainty).

An error: the value failed

A formula that raises an error does not stop the run: the other values are computed. The failed value keeps the last value it gave, and the file records the failure by the error's type:

young_modulus:
  v: 206.33891963549178
  u: 1.0599559413170074
  unit: GPa
  computed: {curve.strain: ed9e87a6f01a, curve.stress: 82a1e45e269c}
  fingerprint: {failed: ZeroDivisionError}

Here the fit of the modulus had two rows left below 0.05 % of strain, and divided by zero.

The full traceback goes to .samplekit/failures/ in the project; samplekit FILE explain VALUE prints it, and so does Enter on the value in the TUI. The command exits with code 2. In Python, compute() finishes the other values and then raises the first failure, naming the others. Reading a failed value gives its last value, with a warning that it failed.

A formula that never returns is stopped by compute --timeout SECONDS: its value fails as TimedOut, and the others run: in a continuous integration, a formula caught in a loop no longer holds the job until its limit. Without --timeout, a formula runs as long as it takes, and Ctrl+C stops the run.

When one command covers several projects and one of them cannot run at all (its model missing, say), the error names that project and the others are still computed.

The model cannot be read

If the model file is missing, there is no Python environment, or the model raises as it is imported, status and compute say so, and give what the files alone can tell: outdated, edited and failed values are known from the files; the values the model has never computed are known only to the model, and are said to be unknown rather than left out in silence.

What the model prints

The model runs in its own process during compute, so its output does not clutter the listing:

  • print(...) and logging below warning go to a log file, whose path is printed at the end of the run;

  • a warning (log.warning(...), warnings.warn(...)) is shown at the end of the run, with its sample and value; several are counted in one line, which -v turns into the list of them: that is how a formula tells you something from inside a run;

  • --show-output shows every line as it comes.

A formula reads nothing either: an input() left in it fails, since a computation runs with nobody before it. A script of the model may ask, in the terminal or in the TUI's window (run a script).

Common mistakes

  • Forgetting an input in depends_on. The value is never marked outdated when that input changes. Declare everything a formula reads.

  • Expecting a formula to propagate uncertainties by itself. It gives what you return; return an uncertainty if you want one.

  • Installing SampleKit in another environment than the project's. The command line uses the one [model] python names; --show-rc says which.

  • Taking a waiting value for a failure. It waits for an input nobody entered; enter it.

  • Running --write on a new model straight away. Run compute alone first, and answer n when it asks to apply.

Where to go next