Write a model¶
This guide is for adding a model to a project: a Python class that says what a sample holds, which values are computed, from what, and how. SampleKit then computes those values, and knows when one no longer holds. The home page builds one step by step on the tensile example; this guide gathers what writing your own takes.
1. The Python it runs in¶
A model runs in the Python environment that [model] python names in
.samplekitrc, where SampleKit's package is installed at the version of the
command line, and nowhere else. samplekit init, in the project's folder,
offers to make it, .venv/, when it is missing (start a
project). Whatever your formulas import, numpy or scipy,
is installed in that same environment: .venv/bin/pip install scipy.
2. Name it¶
.samplekitrc names the model's file and its class:
[model]
path = "model/specimen.py"
class = "Specimen"
python = ".venv"
Both paths read from .samplekitrc's folder. A project set up by init with
a model already has this section, and a model/main.py that runs as it is
and says in comments how to declare each kind of value. A model file you
already have is named where it is, samplekit init --model PATH, without
class: the one subclass of sk.Sample it defines is used. A model may
import modules of its own beside it, a helpers/ package for instance.
3. Declare what a sample holds¶
In the class's __init__, each property is an sk.Property, by kind:
Kind |
Declared as |
|---|---|
measured once, typed in each file |
|
measured several times |
|
computed from others |
|
computed, value and uncertainty apart |
|
a table, its columns |
|
a column computed row by row |
|
a text each file gives, read by a formula |
named in the formula's |
The home page shows each in place: readings and their statistics, values computed from others, a table inside a sample. Two rules hold for every computed value:
It says what it reads, with
depends_on. That list is how SampleKit knows the value is out of date when an input changes: it cannot see what a formula reads, and a name left out is a change never noticed. A formula that reads nothing of the sample saysdepends_on=[].Readings have a value only through the statistic you choose. Without
value=, readings have no value, and nothing is computed from them (readings and statistics).
A formula returns a number, or a value and its uncertainty as a pair; it
propagates uncertainties only as you write it. Every keyword is in the
reference of sk.Property. The model can also
draw figures and run scripts, methods marked @sk.figure and @sk.script
(figures, scripts).
4. Declare their digits¶
A file keeps every digit a formula gives, 25.05586444444445; what tables,
exports and figures show is the precision the project declares. Declare one
for each value a formula gives, or a table shows about six significant
digits and an export every digit:
[property.area]
precision = ".2f"
A value with an uncertainty is shown to its uncertainty, and needs none (precision).
5. Compute¶
status lists what is not current and why; compute alone shows what it
would compute and asks, then shows the results and asks again; --write
computes and writes without asking. Here, after a width measured again:
$ samplekit samples/copper-01.md set width.readings=12.511,12.497,12.505 --write
samples/copper-01.md · 1 change
width.readings 12.509, 12.498, 12.506 → 12.511, 12.497, 12.505
3 readings: 12.511, 12.497, 12.505, their mean 12.5043
they replace the 3 readings it held
its value and its uncertainty, their mean and standard error, wait for samplekit compute
this makes 1 value not current
width outdated — readings
samplekit samples/copper-01.md compute --write recomputes them
written: samples/copper-01.md
$ samplekit status
1 value is not current
sample value state
───────────────────────────────────────
copper-01 width outdated — readings
samplekit compute lists what would run; --write computes and writes
$ samplekit compute --write
model model/specimen.py
✓ copper-01 width
copper-01
value before after
─────────────────────────────────────────────────
width 12.5043 ± 0.0033 mm 12.5043 ± 0.0041 mm
computed 1 value in 1 sample
written: samples/copper-01.md
Only what depends on the change is computed. A formula edited in the model
makes what it computed formula changed, and compute --write computes it
again; compute --rerun runs every formula, whatever is current, and says
what would change.
In the terminal interface, C shows what is not current, of the basket
(the samples Space put aside) or of the samples shown, and computes it on
y; c on a value computes it again, even current; v shows every value not current, with its reason (work in the
terminal interface). From Python, compute() on
a sample or a list computes what is not current, not_current() says what
is, and save() writes (work from Python).
6. When a formula cannot run¶
A value whose input nobody entered waits, and is said so; a formula that
raises fails, its Python traceback shown and the rest computed;
samplekit FILE explain FIELD says, for one value, what it was computed from
and why it is in its state (when a formula cannot
run, models and
formulas).
An example to copy from¶
samplekit example init --example --write writes a small project in a
folder example/, from the folder you run it in: run it beside your
project, not inside it, so that the two stay apart. It has one formula of
each kind, working, and the commands to try.
The templates are a smaller model to start from, with values measured several times, a value computed from them and a table with a computed column, beside a configuration, a sample and a script that go with it: files to download and fill in.
See also¶
Models and formulas: where a model runs, what it may print, and why every formula says what it reads.
The Python API, every keyword.