DKE Library — Reference

2.1 Kinds and the fields you write

Every query that answers “which functions” returns subjects, never display names — the same identity code.Call.caller holds and callers_of(fn) takes. So an answer from one query feeds straight into another, and name stays what it is: an optional label for reading, not an identity.

Three fields decide whether the queries work at all:

• code.Call.caller and code.Call.callee hold the subject you recorded a Function under, not its display name. The queries compare them directly, so display names make every function look uncalled, with nothing to tell you why.
• code.Function.test names a test that reaches the function, and untested reads its absence. Write it only where a test really does reach, or the rule falls silent everywhere instead of where it should be.
• code.Function.called says something in this codebase calls this function, and uncalled reads its absence — the same shape as test. Record it on the CALLEE, next to the Call you record for the same edge. That looks redundant and is not: uncalled reads a field of the function, not the Call kind, so the absence is a fact about this function only when it is recorded here. Recording the Call alone is not enough — write both, or every function you recorded comes back uncalled however many callers the store holds.

code.Function.callers and code.callees are degree — how many distinct functions call this one, and how many it calls. Distinct neighbours, not call sites: a caller that calls you three times is one dependency, not three, and counting sites would rank a function by how chatty its callers happen to be.

They are recorded rather than counted for you, for the same reason called is — and unlike called, write them for every function, zero included. Those above are read by their absence, so a value everywhere silences the rule. callers is read by comparison, and a function nothing calls has a fan-in of zero, which is a fact rather than a gap. Optional and absent-tolerant: record neither and everything else answers the same, with hub simply never concluding.

code.UnresolvedCall is the opposite record: a call you saw and could not name a target for. It asserts no edge, deliberately — a missing edge is a known gap, and a guessed one is a wrong answer no query could tell from a fact. Write caller as the subject of the enclosing function (as on Call), site as the location to look at, and text as the callee exactly as it appears in the source. site is what makes an entry worth having; a subject without one is skipped. This kind is optional and absent-tolerant — see §2.5 for what it buys you.

code.Rationale is a reason the author wrote down, attached to what it explains. Every other kind here is structure — something a reader could recompute from your source. This is the part that cannot be recomputed: why the structure is the way it is.

It is stated, never inferred, for the reason Counterpart is: intent is a claim only a reader can make, and an inferred one produces facts you cannot tell from the real ones. Write subject as the subject of the Function or Class it explains, marker as which convention it was, text as what the author wrote, and site as where to read it in full. text is what makes an entry worth having; a subject without one is skipped.

Which comments count is your producer’s decision, exactly as what counts as a branch is — and the same warning applies in the same direction. A convention wide enough to sweep ordinary comments turns every line in your tree into a fact and rationale_for into noise. Choose something an author had to type on purpose. Ours records WHY: and NOTE: at the start of a comment, uppercase, and nothing else.

code.Function.explained says a reason exists, and unexplained_critical reads its absence — the same shape as test and called. Write it only where a reason really was recorded, or the rule falls silent everywhere instead of firing.

language says what a fact is about — python, cpp, rust, whatever you call it. It is optional, and a store that never records it answers every other question the same. Record it once your store holds more than one language: module is a path, so it hints at the language at best and no query can rely on it, and without language there is no way to ask about one half of a repository. It also tells two producers apart, which matters because branches is whatever your analysis counted, and two producers can both be right on different scales while complexity compares them against one threshold either way.

code.Counterpart records two functions that have to agree — an encoder and its decoder, a writer and its reader, two siblings that ought to guard their inputs alike. Nothing in a call graph says two functions are halves of one contract; that is a claim about intent, and only you know it. State the pair, name in relation what is being counted, and give the count each side handles. left_covers and right_covers count members of that one named set, which makes them comparable to each other and to nothing else.

2.2 Derived and maintained for you

2.3 How to count branches and loops

hotspot fires at a complexity above 10. A fixed threshold over a number you compute yourself only means something if we agree on how it is computed, so here is the rule. Follow it and your numbers are comparable — to your own past numbers, to another producer’s, and to the threshold.

complexity is one, plus one for each decision the function makes:

else, default and a bare case _ are where control lands when none of the decisions above them fired, so they add nothing — three arms and a catch-all is three, not four.

Two scope rules decide what belongs to which function:

• a named nested function is its own Function, with its own counts; its decisions are not charged to the function that contains it;
• an anonymous inline function — a lambda, a closure, a block — counts toward the function containing it. It is part of that function’s text and cannot be called from anywhere else, so there is no other function for its decisions to belong to.

The list is closed. Anything not on it counts nothing, including constructs with a fair claim to being a decision. An assert is the clearest one: it is a conditional failure, and most complexity tools count it — but in some languages it is a macro or a compiled-out call that a reader working from source cannot reliably see, and a rule that some producers can follow and others cannot is the problem this rule exists to solve. A number everyone computes the same way is worth more than a number that is arguably more faithful.

If you want a different scale — a stricter threshold, a metric of your own — define your own module named code.

2.4 Queries

2.5 What the answers can and cannot mean

The queries are only as good as the data, and for a codebase that has consequences worth stating plainly.

A call graph derived from source is a lower bound. Python decides calls as it runs, so anything reading source sees the calls the source makes plain and no others — a call through a variable, a handler table or getattr is not visible. Every edge you record that way is real; edges are missing. That matters most for uncalled(): a function reached only dynamically appears there. Read it as candidates to look at, never a list to delete.

How loose that bound is, is measurable. Record an UnresolvedCall wherever your producer sees a call and cannot name the target, and dispatch_sites() lists them: the location, and the callee as written. Read it beside uncalled() — any of those sites could be the call that a function on that list is reached by. A codebase with two dispatch sites and one with two hundred deserve very different trust in the same uncalled() answer, and this is what tells them apart. Nothing on the list is a defect by itself: a plugin table, a callback and a decorator all work exactly this way. It is a measure of how much of your call graph is decidable by reading.

Recording none of them is fine. The kind is absent-tolerant — everything else answers the same, and dispatch_sites() returns nothing.

untested inherits that bound, since reaching a function is worked out over the same graph — and reaching is not executing, because a branch may never be taken. Read it the same way.

critical() cannot tell deliberate from overlooked, and unexplained() can. Two functions can be identical in every structural respect — same complexity, neither reached by a test — and be entirely different objects: one whose author wrote down why it is shaped that way and why it is not tested, and one that says nothing. critical() returns both, because everything it reads is structure. Record Rationale and explained and unexplained() is the same list with the accounted-for taken out. A short unexplained() under a long critical() is a good result: the risk is known and written down rather than absent. Record none of it and unexplained() is simply critical() again, which is where you were.

There is no dependency age, and that is the schema being honest rather than an omission. Python’s package metadata carries no release date, so an age could only come from asking an index — which means sending a dependency list to a third party. A field nothing can honestly fill is worse than no field, because it reads as a capability.

unused_dependencies() matches by name, so a distribution whose import name differs from its package name (Pillow is imported as PIL) will look unused.

A subject missing the field a query reads is skipped, not fatal. You are never obliged to fill every field of a kind, and one half-written subject does not take out the answer for the complete ones beside it — a Dependency with no name, a Counterpart with no relation, an UnresolvedCall with no site and a Rationale with no text are each passed over, and everything else answers as it would have. So a partial record costs you that record and nothing more.

3.1 Kinds and the fields you write

A record is a subject of identity.Record, and name is what it is called for reading. The rules do not need it: every name a statement uses is a record to them, recorded or not. So a misspelt name in a statement is not refused. It becomes a record of its own, and shows up under the misspelling in same_as. identity.unrecorded() lists every name a statement uses that no record carries.

A statement is a subject of Same, Possibly or Different, and a and b hold the names of the two records it is about. The statement’s own name is yours to choose, and only keeps two statements apart. Its source is the source you write it with, so who said two records are the same is recorded with the saying:

remember(identity.Record.alice.name, "Alice Smith", "crm")
remember(identity.Record.asmith.name, "A. Smith", "billing")
remember(identity.Same.m1.a, "alice", "crm")
remember(identity.Same.m1.b, "asmith", "crm")

3.2 Derived and maintained for you

Two relations are concluded as well. A relation is read with both record names, SameEntity.alice.asmith, and holds True or nothing:

A relation a module concludes is not namespaced by the module: it is SameEntity, never identity.SameEntity, in any unit, whether or not that unit imports identity (Python Reference §9.6). That is what lets your own rules read it. Two consequences follow from the same rule. A path you write naming SameEntity or PossiblySame, with no class of that name in scope, writes into these relations. And a unit that declares a class named either one reads its own class by that name, so its rules cannot reach the relation.

3.3 Queries

3.4 Carrying a fact across a link

identity does not know what your records hold, so it cannot carry an email or an address from one record to another. A rule of yours can, by reading SameEntity. Name your own subjects after the records they describe, and conclude the carried value into a field of its own:

class Person:
    email: string

@rule
def email_seen():
    for p in Person, q in Person:
        if SameEntity.p.q == True:
            p.email_seen = q.email

p.email_seen then holds the email of every record that names the same thing as p, p’s own included. Where two of them differ, the field holds both, and the difference is an ordinary disagreement: conflicts() reports it, get(Person.p.email_seen) answers each value, and why names the record each one came from. Carrying a field onto itself (p.email = q.email) is not the way to do this: a field a rule concludes cannot also be written, so the rule would have nothing to copy.

A record that is in no chain is not the same entity as itself, so the rule above carries nothing to it. Where you want every record’s own value included, say so with a rule of its own:

@rule
def own_email():
    for p in Person:
        if p.email != "":
            p.email_seen = p.email

3.5 What the answers can and cannot mean

SameEntity is exactly as right as your Same statements. One wrong statement joins two entities, and everything either one reaches. The conclusion names what it rests on — why(SameEntity.x.y) answers the statements, with the conclusions between them — and forgetting the wrong one withdraws every conclusion it supported, and nothing else.

A Different statement does not undo a Same one. Where they disagree, both stand, and the disagreement is reported on the statement and on both records. Which source to believe is yours to decide; the module decides nothing.

A name is matched exactly. alice and Alice are two records, and so are a record and its misspelling. Nothing here compares spellings; a statement is what says two names are one thing. unrecorded() is the check that catches a statement naming a record you never recorded.

The relation grows with the square of an entity. An entity of n records holds n² SameEntity conclusions, one for each ordered pair. That is what makes every question about it one read, and it is the cost to keep in mind before stating that ten thousand records are one thing.

4.1 Kinds and the fields you write

A claim is a subject of argument.Claim, and text is what it says, for reading. As in identity, every name a statement uses is a claim to the rules, recorded or not, so a misspelt name becomes a claim of its own. argument.unrecorded() lists every name a statement uses that no claim carries.

A statement is a subject of Support, Attack or Weakening. It says that the claim named in by supports, attacks or weakens the claim named in target, and its source is who says so. A statement counts once both of its fields are written; one with only a target bears on nothing.

remember(argument.Claim.leak.text, "The outage was caused by a memory leak", "ops")
remember(argument.Claim.flat.text, "Memory stayed flat for the whole outage", "metrics")
remember(argument.Attack.k1.by, "flat", "metrics")
remember(argument.Attack.k1.target, "leak", "metrics")

4.2 Derived and maintained for you

argument concludes no relation, so nothing it derives lives outside its own kinds.

4.3 Queries

4.4 What the answers can and cannot mean

Three answers, and silence. A claim stands when nothing attacks it, falls when a claim that stands attacks it, and stands again when every claim attacking it falls. An attacked claim that is none of these is open: no query names it. Two claims that attack each other are the simplest case, and a longer chain of attacks is the other. argument stops after these two steps on purpose, so that every claim it does name is settled by what you recorded. An open claim is one the statements do not settle this way, not one that has been found to fall.

A weakening is reported, never counted. It does not make a claim fall and it does not answer an attack. Use it for evidence against a claim that you want on record without deciding anything.

A support is not a defence. Supporting a claim does not protect it from an attack. What a support does is carry a doubt: contested_premises() names the claims that support something while being attacked themselves, which is where an argument rests on ground that is disputed.

It reads your statements, not your data. A claim here is a name and a sentence. Where two sources give a field of one subject two different values, that disagreement is already the store’s own finding (conflicts()), and you do not need this module to see it. argument is for claims that bear on each other because someone said they do.

5.1 Kinds and the fields you write

A commitment is something you have undertaken to do. action says what, due is the datetime it is due, and serves names the goal it is for, if it serves one. An obligation is something you owe owed_to, and is read the same way; the difference is that you did not choose it. Either is open until done_at records when it was done.

A prohibition is an action you may not take. Write it with a validity window to say when it applies (a change freeze, a quiet period) and it applies only then. Written without one, it always applies. A prohibition covers a commitment or an obligation whose action is exactly its own.

As in identity, every name a commitment serves is a goal to the rules, recorded or not. agenda.unrecorded() lists every such name that no goal carries.

remember(agenda.Goal.launch.text, "Launch the new site", "me")
remember(agenda.Commitment.docs.action, "write the docs", "me")
remember(agenda.Commitment.docs.due, datetime("2026-10-02T17:00:00Z"), "me")
remember(agenda.Commitment.docs.serves, "launch", "me")
remember(agenda.Prohibition.freeze.action, "deploy", "ops",
         datetime("2026-10-05T00:00:00Z"), datetime("2026-10-12T00:00:00Z"))

Moving a due date. Move one with update, under the source that set it:

update(agenda.Commitment.docs.due, datetime("2026-10-06T17:00:00Z"), "me")

The date it replaces is kept, and agenda.previous_dues("Commitment.docs") reads it back. A revision replaces only what the same source said, so a date a different source gives sits beside the first instead of replacing it, and the item is then unsettled (§5.4).

5.2 Derived and maintained for you

Two standing constraints report through checkup rather than through a query. agenda.nothing_forbidden_committed names each open commitment a prohibition covers now, and agenda.nothing_forbidden_owed names each such obligation. Neither refuses a write: recording a commitment you may not keep is not an error, and the report is how you find it.

5.3 Queries

at is a datetime and span a duration. A query answers commitments and obligations as Commitment.<name> and Obligation.<name>, which is also how previous_dues takes one:

import agenda

def this_week():
    now = datetime("2026-10-01T09:00:00Z")
    for item in agenda.overdue(now):
        print("overdue: " + item)
    for item in agenda.due_within(now, duration("P7D")):
        print("this week: " + item)

5.4 What the answers can and cannot mean

The moment is always yours to name. overdue(at) answers from what the store holds now about the moment at. An item you moved yesterday is read at its new date, whatever moment you ask about; the dates it had before are what previous_dues returns.

An item done after the moment was still open at it. done_at is a moment like any other, so an item finished on Wednesday counts as open when you ask about the Tuesday before. That is what makes a past moment answerable.

Unsettled is not overdue. When two sources give an item two due dates, or two completions, the item has no one place in time. overdue and due_within leave it out rather than pick one, and unsettled(at) names it, so nothing goes missing without a trace. conflicts() shows the two values.

Forbidden and blocked are two questions. forbidden(at) asks what you may not do at a moment: during a change freeze it names every open commitment to deploy, whenever each is due. blocked() asks which items cannot be done on time without doing what you may not: those due while their action is forbidden. Move a blocked item’s due date out of the prohibition’s window and it is no longer blocked, while forbidden at a moment inside the window still names it.

Forbidden is a report, not a veto. A commitment to an action a prohibition covers is still a commitment. The module concludes forbidden on it for as long as the prohibition applies, and checkup names it while it is open; what you do about it is yours. An obligation that is forbidden is the sharper case (you owe what you may not do), and it is reported the same way.

Matching is exact. A prohibition covers an action written exactly as it is: "deploy" does not cover "deploy the site". Write the action the same way in both places, or record one prohibition for each action.

6.1 Kinds and the fields you write

A gate is one operation of a circuit: op names the operation, a the qubit it acts on and b the second qubit of a two-qubit gate, and step its position. circuit names the circuit it belongs to; the gates that name none are one circuit together. Qubits are named, and a compiled circuit names them by number, as text. A coupler is a pair of qubits your chip can act on together, in either order. Qubit is for your own reading; no rule reads it.

An op is an operation’s properties: how many qubits it takes, and whether it is diagonal. The module records them for every operation it simulates, and for id and rzz, when it is imported; record another the same way.

A device is facts too: its physical qubits, and the operations it runs natively on each qubit and each ordered pair, with each one’s measured error, its duration and when it was measured. A circuit names the device it was compiled for and the digest of the text it was written from. A result is something computed outside the store, such as a compilation, a comparison or the bits a run measured: the circuit it is about, the circuit it came from and the device it was computed for, each with the digest its producer read, and the producer, its settings, its seed and the outcome.

You do not have to write device facts or results by hand. dkepy’s dke.quantum.device writes a device from a calibration snapshot, and dke.quantum.provenance writes a result and the digests it names:

dke-quantum-device ./torino --max-bytes 40000 > torino.dpy

State is written by quantum.save and read by quantum.load (§6.3), never by hand.

6.2 Derived and maintained for you

A result that names no source, or no device, counts as current on that part.

Two standing constraints report through checkup. quantum.every_pair_coupled names each uncoupled gate, and quantum.every_gate_legal each gate its device cannot run as written. Neither refuses a write.

6.3 Queries

Simulation reads and writes no fact. psi is a state, q a qubit’s index (qubit 0 is the lowest bit of an amplitude’s index), and theta an angle in radians:

A Clifford circuit can run on a stabilizer tableau instead, whose size grows with n² rather than 2ⁿ:

Two circuits can be compared for equality up to a global phase, which is what a compiler must preserve. A step is a gate’s name, its qubits and an angle:

A circuit of x, cnot, ccx, swap and cswap, with the signs z, cz and ccz, sends every basis state to one basis state under a sign of +1 or -1, so it can be checked on every input with integers alone, at any width. Qubit q of an input is bit q of the input’s index. Two circuits are equal when, on every input, they give the same output bits under one sign shared by every input: a sign that differs on some inputs only is not equal, and one that differs on all of them is. A circuit meets a specification when, on every input of its input qubits ins, those qubits are unchanged, the output qubits outs hold the value want gives for it (bit j of a value on qubit outs[j]), every other qubit is 0 again, and the sign is the one signs gives (1 for -1; an empty list is +1 for every input). The circuit starts with every qubit but ins at 0, and want is one value for each of the 2**len(ins) inputs, which the caller computes with a function of its own. Both answer (holds, inputs, first, why): the number of inputs checked, the first input that fails or -1, and the reason, which is "output" or "sign" for two circuits and "input", "ancilla", "output" or "sign" for a specification, the first that holds at that input.

A circuit may also measure. ("mx", [q], 0.0) measures qubit q in the X basis and leaves it 0. Its outcome is not drawn from anything: it is one bit of the case being checked, as a seed is an argument. Under outcome 1 it negates the sign on every input where q held 1, and under outcome 0 it changes no sign. A step named x_if, cnot_if, ccx_if, z_if, cz_if, ccz_if, swap_if or cswap_if is the gate it names, run only where an outcome was 1: it takes the measured qubit first and then the gate’s own qubits in the gate’s order, so ("cz_if", [t, a, b], 0.0) is cz on a and b where the latest mx of t before it gave 1. A step whose first qubit no earlier mx measured is refused. The outcomes are numbered by the mx steps in step order, outcome j being the j-th. rev_meets holds a circuit over every assignment of them, so a circuit of M measurements is checked on 2M times as many cases, and a case i is input i mod 2len(ins) under the outcomes i div 2len(ins); the number it answers is the count of cases, and a check of more than 262 cases is refused. With it a qubit that holds the AND of two others, computed by a Toffoli gate, is uncomputed without one: measure it, and where the outcome is 1 apply a cz to the two. rev_same takes no circuit that measures, since it looks at every input of every qubit, and a measured qubit that starts at 1 is reset and not undone; a circuit that measures is held to a specification, where every qubit but the inputs starts at 0.

A state can be kept in the store by a name you choose, so a circuit longer than one run is a series of calls that pass nothing but steps. quantum.save(name, psi) keeps one, quantum.drop(name) forgets it, quantum.keep(name, b) keeps bytes quantum.packed answered, and quantum.collapse(name, q, bit, norm) collapses a kept state; each answers nothing.

Over the facts you have loaded:

import quantum

def bell():
    psi = quantum.zero(2)
    psi = quantum.h(psi, 0)
    psi = quantum.cnot(psi, 0, 1)
    print(quantum.probabilities(psi))

6.4 What the answers can and cannot mean

Equal is up to a global phase. Two circuits that differ only by a global phase are the same physical operation, and the comparisons treat them as one. overlap asks for one phase across every basis state, so a missing rz or one of the wrong sign does not pass.

A device is judged by its own facts. A gate whose circuit names a device is judged by that device’s qubits and native operations, and couplers say nothing about it. A circuit naming a device the store holds no facts for has every gate refused, which is also how a misspelt device name shows itself.

Only the 256-bit generator can stand behind a secret. lcg_next has fewer than 2³¹ seeds, so anyone can try every one of them; it is for runs you want to replay. A key for chacha_uniform is 8 words from 0 to 0xFFFFFFFF, which list(struct.unpack("<8I", secrets.token_bytes(32))) draws in Python. The key is an argument like any other: it travels to the service in the program you send, and the service sees it. A secret that is to stay on your own machine is drawn on your own machine.

The moment is yours to name. The store keeps no clock, so stale_gates takes the moment and the oldest calibration you accept, and asking about that moment again gives the same answer.

A result holds only while what it read is current. Change a circuit’s digest, or load a recalibrated device, and every result that read the old one stops holding, with a reason naming what moved. A result’s producer, settings and seed are kept as its recipe and are not judged: no rule can know whether a producer is still current. The store compares digests and never computes one, so a digest is the writer’s to keep true.

7.1 Kinds and the fields you write

Every year is a calendar year, written as an int, and every boundary is the first year WITHOUT something. The horizon is the first year you assume a quantum computer able to break the vulnerable algorithms exists. An algorithm’s quantum is "vulnerable" when a quantum computer breaks it, and its strength is its classical security strength in bits. Data’s shelf_life is how many years after it is protected it must stay protected: for a signature, how long it must be trusted. A system’s migration is how many years moving it off a vulnerable algorithm takes. A deadline is the first year a vulnerable algorithm of at most strength bits may not be used. A use is one system using one algorithm to protect one kind of data, and migrated is the first year it no longer relies on the algorithm, planned or done; a use with none has no plan.

dkepy’s dke.pqc.cbom writes the algorithms and uses that a cryptographic bill of materials states. The rest are your own facts, recorded beside them:

dke-pqc-cbom ./cbom.json --max-bytes 40000 > cbom.dpy

7.2 Derived and maintained for you

Two standing constraints report through checkup. pqc.no_late_plan names each late use and pqc.no_missed_deadline each use that misses its deadline. Neither refuses a write.

7.3 Queries

Each answers use names.

import pqc

def plan():
    for u in pqc.priority():
        print("start: " + u)
    for u in pqc.noncompliant():
        print("misses a deadline: " + u)

7.4 What the answers can and cannot mean

The year is yours to name. The store keeps no clock. Every conclusion is a year, and remaining takes the year you ask about, so asking about that year again gives the same answer.

Disagreement is kept, not resolved. When a scanner and a system’s owner record different algorithms, or two policies different shelf lives, every value is reasoned about. A use is late, exposed or remaining if any value on record makes it so, and priority places it by the earliest year it must start. A use’s deadline is likewise the earliest year of any value of any deadline that covers its algorithm: one source’s year, never two added. unsettled() names every use where a value of its own, or of the horizon, shelf life or migration time it is reasoned about with, disagrees, so you can settle it. A deadline’s year is not among them; why on the use’s deadline names the year that placed it, beside every year it was chosen from.

An unclassified use is not a safe one. The rules conclude nothing about a use whose algorithm’s standing is not recorded, so it appears in no answer but unclassified(). An inventory with one in it is not yet a safe inventory.

8.1 Kinds and the fields you write

A voice’s low and high are its range, as MIDI note numbers. A key’s tonic is a pitch class, 0 for C up to 11 for B, and its mode is "major" or "minor"; a degree is one pitch class that belongs to it. A note names its voice, its beat, its pitch and, to be checked against one, its key. A bar starts at start and lasts length, counted from the start of the piece in a unit you choose, such as a sixteenth, and pulse is the length of its beat; bars of different lengths are how a change of metre is written. A tone is a note of a melody, for its rhythm, and a rest is a tone too.

Five scripts write these facts for you, under the source harmony:

• harmony.satb() writes the four voices of a chorale, bass to soprano, with the ranges bass E2 to C4, tenor C3 to G4, alto G3 to D5 and soprano C4 to G5. Textbooks differ by a note or two; update a range to use another.
• harmony.key(name, tonic, mode) writes a key and its degrees. A minor key takes its raised sixth and seventh as well as its own degrees.
• harmony.chord(beat, key, bass, tenor, alto, soprano) writes one chord’s four notes, named for their voice and beat: bass1 to soprano1 for beat 1. Writing a beat again corrects it.
• harmony.bars(count, length, pulse) writes count bars of one metre, m1 onward, and harmony.melody(durations) a melody’s tones end to end, t1 onward. Writing either again replaces what an earlier call wrote: it forgets the bars or tones it had numbered past the new end.

8.2 Derived and maintained for you

Three relations are concluded between two notes on one beat. harmony.Fifths.a.m holds when the voice of note a and the lower voice of note m are a fifth apart on that beat and again on the next, and both move: consecutive fifths, in contrary motion too, with a compound interval counted as its simple form. harmony.Octaves is the same for octaves and unisons, and harmony.Crossing.a.m holds when a’s voice sounds below m’s, which is placed under it.

A chord is read from the intervals above its bass. Major, minor and diminished triads are read in root position and in first and second inversion, a major or minor triad with its fifth left out, and a dominant seventh in root position, with its fifth left out, and in its three inversions. These are the shapes figured bass names: a first inversion is a 6, a second a 6/4, and a seventh’s inversions are a 6/5, a 4/3 and a 4/2.

8.3 Queries

import harmony

def mark():
    for f in harmony.faults():
        print(f)
    print(harmony.readings("bass1"))

8.4 What the answers can and cannot mean

A mark is the rule, not a verdict. The rules are the ones a teacher of four-part writing marks, written exactly. A note outside the key is marked though it may be a deliberate chromatic note, such as the raised fourth of a secondary dominant, and consecutive fifths are marked whatever the style of the piece. What the module does not check is listed rather than implied: hidden fifths and octaves, doubling, the resolution of a leading note or a seventh, melodic intervals, and more than four voices.

A chord takes every reading inside it. A rule reads exactly the intervals it names, so a dominant seventh is read as a major triad as well, a chord with both a major and a minor third is read as both, and a chord of no shape the rules know, such as an augmented triad, has no reading.

A correction replaces; a disagreement is kept. chord() writes under the source harmony, so writing a beat again replaces its notes and withdraws every mark they no longer support. A note written under another source is held beside the first rather than replacing it. Every mark it reaches is drawn from both values, a line of faults() names it with each voice and beat it has, and harmony.unsettled() names it. The one exception is a mark that asks for something to be missing: a note is outside the key only when no value of its pitch is in the key, and a chord is read with its fifth omitted only when no value supplies the fifth. Only filled_of refuses, and only a disputed bar.

A bar’s fill is not drawn from a tone bound to it twice. How much a bar’s tones fill is a sum, and a sum adds every value it reads: a tone whose duration a second source writes, even the same duration, would be counted twice, and the bar would read as overfilled where every source fills it. So while a tone is bound to its bar twice, the bar is disputed: no filled and no miscounted is concluded for it, rhythm_faults() names it as bar m1: disputed, filled_of refuses it, and why_not on its filled names the dispute. A tone with no duration fills nothing and hides no dispute. Forgetting the claim that is not to stand settles it. A tone whose onset two sources disagree on starts in each bar a value puts it in, so each of those fills is one source’s.

The calculations are exact. Each value script computes what the same formula computes in CPython, to the last bit. Prime forms are given under both published criteria, which disagree for six set classes.

9.1 Kinds and the fields you write

A unit is named by letters, digits and underscores, such as "N", "lbf_s" or "m_per_s2". A unit whose zero is not SI’s, such as a degree Celsius, is not a factor and is not written. A quantity is a value in a unit, by a name you choose; its expects is the unit its reader takes it in, where it is handed from one system to another. A factor is one quantity in an equation written as a product of powers. Write every power on the left side positive and every power on the right side negative, so F = m a is F to the 1, m to the -1 and a to the -1. A pure number such as the 1/2 of E = m v²/2 has no dimension and needs no factor, and a square root is written by doubling every power in the equation. A resistor names its resistance in ohms and the group it is joined in, "series" or "parallel".

Eight scripts write these facts for you:

• physics.si_units() writes the list of units, each under the source that gives its value: the SI Brochure (9th edition, 2019) for the SI units and those defined by them, and NIST Special Publication 811 for the inch, foot, mile, miles per hour, pound, pound-force, pound-force second, foot-pound, pound per square inch, atmosphere and calorie. A pound is 0.45359237 kg and a pound-force a pound under standard gravity, 9.80665 m/s².
• physics.unit(name, mass, length, time, current, temperature, factor, source) writes one unit under the source you give.
• physics.quantity(name, value, unit) writes a quantity, and physics.expect(name, unit) the unit its reader takes it in. Writing a name again corrects it.
• physics.factor(equation, quantity, power) writes one factor of an equation.
• physics.resistor(name, ohms, group) and physics.group(name, joined) write a resistor and the group it is joined in.

9.2 Derived and maintained for you

A hand-over is a quantity written in one unit that its reader takes in another. If both have one dimension, the value is converted and converted reads it in the expected unit. If they have different dimensions, no conversion makes it the quantity the reader wants: a mass in kilograms where a force in newtons is expected is marked "incompatible". A quantity given in the unit it expects is no hand-over and is marked nothing.

9.3 Queries

import physics

physics.si_units()
physics.quantity("thrust", 5.0, "lbf")
physics.expect("thrust", "N")
physics.quantity("mass", 2.0, "kg")
physics.expect("mass", "N")

print(physics.checks())
print(physics.converted("thrust"))
print(physics.si("mass"))

prints ['handed over: mass in kg where N is expected, incompatible', 'handed over: thrust in lbf where N is expected, convert'], 22.2411080763025 and 2.0.

9.4 What the answers can and cannot mean

A consistent equation is not a true one. consistent says the dimensions on both sides are the same, and E = m v² and E = 2 m v² are equally consistent. An unbalanced equation is wrong, and dimension says by how much: E = m v leaves L1 T-1. What the module does not do is solve an equation, or decide whether a quantity is plausible.

A unit is only as good as the list. A quantity in a unit the list does not hold has no si and no dimension, and checks() names it. An equation with such a factor is judged neither consistent nor unbalanced, and dimension reads unknown unit. The list written by si_units() is the units it lists; there is no degree Celsius, whose zero is not SI’s, and no mole or candela. A unit you add with physics.unit is as good as the factor you give it.

A circuit of series and parallel groups is a sum. physics.resistance adds and reciprocates; a circuit that is not built of series and parallel groups, such as a bridge, is solved with physics.solve or physics.bridge. A group’s members are resistors, not groups, so a group inside a group is not added.

A correction replaces; a disagreement is kept. The writing scripts write under the source physics, so writing a quantity or a resistor again replaces its value and withdraws every conclusion that rested on the old one. A value written under another source is held beside the first. Every conclusion it reaches is drawn from both values, and physics.unsettled() names the fact.

A sum is not drawn from a member bound to it twice. An equation’s dimensions and a group’s resistance are sums, and a sum adds every value it reads: a resistor whose ohms a second source writes, even the same ohms, would be counted twice, 400 ohms where every source says 300. So while a member is bound to its sum twice, that sum is disputed and not concluded, and neither is what rests on it: dimension reads disputed, resistance refuses the group, checks() names each, disputed_equations() and disputed_groups() list them, and why_not on the sum names the dispute. A share both powers of a factor agree on, as every share of a dimensionless unit does, disputes nothing, and a parallel group is disputed only by a resistance that differs, since an equal one is one conductance. A member with no value of the sum, such as a factor in a unit not in the list or a resistor of 0 ohms in a parallel group, adds nothing and hides no dispute. Forgetting the claim that is not to stand settles it. A factor whose equation, or a resistor whose group, two sources disagree on counts in each a value names, so each of those sums is one source’s. No other query refuses.

The calculations are exact in the sense that matters. Each computes what the same formula computes in CPython. The integrators are what they are called: the Euler orbit of eccentricity 0.5 drifts a long way in ten periods and the fourth-order Runge–Kutta one hardly at all. A value script has no inputs but its arguments and reads nothing from the store. A calculation checks its arguments only where a refusal is the answer, with ValueError: small_period and period refuse a length below 0 or a g not above 0, period an amplitude outside -π to π, pendulum an amplitude not above 0 or above π and a length or a step not above 0, agm a number below 0, orbit an eccentricity outside 0 to below 1, and bridge a resistance not above 0. pendulum integrates for up to the exact period, so a pendulum released near the top is timed rather than answered with 0.0, as 1.0.2 did, and refuses a step too long to reach the vertical. solve reads a system as singular only where a pivot is exactly 0, as mathematics.solve does, where 1.0.2 read any pivot under 1e-300 so. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

10.1 Kinds and the fields you write

An element is named by its symbol: its atomic number z, its valence, the number of bonds it forms in an organic molecule, which is 0 for an element that forms none there, and its standard atomic weight. An atom is named by you, and gives its element’s symbol and the molecule it belongs to. A bond goes from atom a to atom b with an order of 1, 2 or 3; a bond is written as its two halves, one from each atom, so each reaches the other. A species is a substance in a state, such as "water_l" for liquid water, with its standard enthalpy of formation in kJ/mol. A term is one species of a reaction with its coefficient, positive for a product and negative for a reactant.

Six scripts write these facts for you:

• chemistry.elements() writes the elements the rules read: H, C, N, O, Na, P, S, Cl, K, Ca, Cr, Mn and Fe, with the abridged standard atomic weights of IUPAC’s Commission on Isotopic Abundances and Atomic Weights and each element’s usual valence in an organic molecule. Call it once before reading a structure. chemistry.element(symbol, z, valence, weight) writes one.
• chemistry.atom(name, symbol, molecule) writes an atom.
• chemistry.bond(a, b, order) writes both halves of a bond, named a-b and b-a. Writing a bond again corrects it.
• chemistry.species(name, formation) writes a species and its enthalpy of formation in kJ/mol.
• chemistry.term(reaction, species, coefficient) writes one species of a reaction, named reaction, - and species.

10.2 Derived and maintained for you

Groups are read from the bonds. A carbonyl carbon with a single bond to an oxygen that carries a hydrogen is a carboxylic acid; to an oxygen that carries none, an ester; to a nitrogen, an amide. A carbonyl carbon that carries a hydrogen and has no single bond to an oxygen or a nitrogen is an aldehyde, and one with single bonds to two different carbons is a ketone. An oxygen with one hydrogen bonded to a carbon that is not a carbonyl carbon is an alcohol, and a nitrogen bonded to carbon, none of it a carbonyl carbon, is an amine. The group is concluded on the atom that carries it.

A reaction’s enthalpy is Hess’s law. The enthalpy of a reaction is the sum, over its species, of each coefficient times that species’ enthalpy of formation, whatever path the reaction takes.

10.3 Queries

import chemistry

chemistry.elements()
chemistry.atom("a1", "C", "methanol")
chemistry.atom("a2", "O", "methanol")
chemistry.bond("a1", "a2", 1)

for g in chemistry.groups("methanol"):
    print(g)
print(chemistry.formula("methanol"))
print(chemistry.faults())
print(chemistry.unsettled())

prints alcohol, CH4O, [] and []: the oxygen carries one hydrogen and is bonded to a carbon that is no carbonyl carbon, the carbon carries three, and nothing is overbonded or in dispute.

10.4 What the answers can and cannot mean

A structure is its bonds and nothing more. The rules read atoms, bond orders and the one valence each element has in the store. They do not represent charge, rings, aromaticity or stereochemistry, a second valence for an element such as sulfur or phosphorus, or any group beyond the seven named above. A nitrogen is read as an amine only while every bond it has is single, so a nitrile’s or an imine’s nitrogen carries no group, and an ether, which carries no group the rules name, has none.

Nothing is concluded without the elements. Before chemistry.elements() is called, or for an atom whose symbol has no Element, an atom has no valence and so no hydrogens, and its molecule’s formula has none of its hydrogens. An element of valence 0, such as sodium or iron, gives its atoms no hydrogens whatever their bonds, and its weight: a sodium bonded to a chlorine reads ClNa and weighs 58.44.

A correction replaces; a disagreement is kept. atom(), bond(), species() and term() write under the source chemistry, so writing a bond again replaces it and withdraws every group and weight that rested on the old one. A fact written under another source is held beside the first. Every conclusion reached from it is drawn from both values, and chemistry.unsettled() names it.

A sum is not drawn from a member bound to it twice. An atom’s bonds, a molecule’s weight and hydrogens and a reaction’s enthalpy are sums, and a sum adds every value it reads: a sulfur atom whose element’s weight two sources give as 32.06 and 32.065 would be weighed at both, and a bond whose order a second source writes, even the same order, counted twice. So while a member is bound to its sum twice, that sum is disputed and not concluded, and neither is what rests on it. An atom whose bonds are disputed has no hydrogens or mass, so its molecule is disputed too rather than weighed without it. weight() refuses a molecule whose weight is disputed, formula() one whose hydrogens are, and enthalpy() a disputed reaction; disputed_molecules(), disputed_reactions() and faults() name them, and why_not on the sum names the dispute. A sum both sources agree on stands: the sulfane’s formula reads H2S while its weight is disputed. Forgetting the claim that is not to stand settles it. An atom whose molecule, a bond whose atom, or a term whose reaction two sources disagree on counts in each a value names, so each of those sums is one source’s.

A formula counts each atom once. An atom two sources both give as oxygen is one oxygen. One they give as oxygen and as sulfur is refused by formula(), which names the atom, until one element is forgotten.

An incomplete reaction is a partial sum. A term whose species has no enthalpy of formation adds nothing, so chemistry.enthalpy() answers the sum of the terms that have one, and chemistry.faults() names the reaction as incomplete.

A bond past its valence is marked, not refused. An atom bonded past its valence is overbonded and carries fewer than 0 hydrogens, which lowers its molecule’s hydrogens and so its formula. chemistry.faults() names it.

balance answers only when the equation has one balance. An equation that balances in more than one independent way, or in none, answers [], as does one whose balance needs a coefficient of 0 or less. The coefficients are exact integers, found without rounding.

The pH and kinetics are calculations, not measurements. chemistry.ph() takes water’s ion product as 1.0e-14 and ignores ionic strength. The Runge-Kutta scripts approach their closed forms as dt shrinks. A calculation checks its arguments only where a refusal is the answer, with ValueError: charge_ph, ph and titration refuse a concentration or a volume below 0, the kinetics scripts a rate constant or a time below 0, consecutive a step not above 0 and one so long for the rates that the integration diverges, and equilibrium_exact a constant or a concentration below 0. equilibrium_exact takes the smaller root as 2 k a0 b0 / (p + r), which subtracts nothing, where 1.0.2’s (p - r) / 2k lost digits to cancellation, all of them for a small constant: at constants from 1e-3 to 1e3 it is within 3 units in the last place of the exact root, where 1.0.2 was off by a median of 5 and up to 89 million. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

11.1 Kinds and the fields you write

A compound’s medium is True for one the growth medium supplies. A reaction’s s1 and s2 are its substrates and p1 and p2 its products, each the name of a compound; leave s2 or p2 unwritten for a reaction with one. A family has a mode. A person names its family, its mother and father where known, its sex, "F" or "M", and whether it is affected.

Four scripts write these facts for you:

• biology.medium(name) marks a compound the medium supplies, under the source medium.
• biology.reaction(name, s1, s2, p1, p2) writes a reaction under the source network. Pass "" for a second substrate or product the reaction does not have.
• biology.family(name, mode) writes a family, and biology.person(name, family, sex, affected, mother, father) a person, under the source pedigree. Pass "" for a parent not recorded.

Writing a name again corrects it. Passing "" writes nothing, so it does not withdraw a second substrate, a second product or a parent an earlier call recorded: write the name you mean instead.

11.2 Derived and maintained for you

Two relations are concluded between people. biology.Parent.c.p holds for each parent recorded of a child c. biology.Ancestor.x.y holds for each parent, each parent’s parent, and so on to the first generation recorded.

A scope is concluded from the medium outward. A reaction that runs makes its products reached, and those start the next reactions. A cycle of reactions that make each other’s substrates is reached only while something outside it supplies one of them; when the medium stops supplying that compound, the cycle is withdrawn with it.

Descent. A child is inbred when its mother and father have an ancestor in common, or when one parent is the other’s ancestor: cousins, siblings, an uncle and a niece, a father and a daughter.

Carriers. In a recessive family, the unaffected parent of an affected child carries the allele, and so does the unaffected child of an affected parent. In an X-linked recessive family, the unaffected mother of an affected son carries it, and so does the unaffected daughter of an affected father.

What a mode cannot explain. An affected child of two unaffected parents in a dominant family; an unaffected child of two affected parents in a recessive one; in an X-linked recessive family, an affected daughter whose father is unaffected, and an unaffected son whose mother is affected.

11.3 Queries

import biology

biology.family("marsh", "autosomal recessive")
biology.person("ada", "marsh", "F", False, "", "")
biology.person("ben", "marsh", "M", False, "", "")
biology.person("cass", "marsh", "F", True, "ada", "ben")
biology.reaction("hexokinase", "glucose", "", "g6p", "")

print(biology.carriers("marsh"))
print(biology.needs("g6p", ["xylose", "glucose"]))
print(biology.period("1000"))

11.4 What the answers can and cannot mean

A scope is reachability, not growth. A compound is reached when a chain of reactions leads to it from the medium. The module does not check that a reaction is balanced, runs in the direction written, has its enzyme or is fast enough, and a reaction written as two directions is two reactions.

needs() asks, and writes nothing. For each candidate it supposes that compound is in the medium alone, asks whether the target is then reached, and discards the supposition. The medium, the scope and every other fact are as they were afterwards. A target already reached is answered by every candidate, and a candidate that is the target itself is answered.

Carriers and unexplained members assume a model. Every pedigree conclusion assumes that the trait shows in everyone who has its genotype, and that no new mutation arose in the family. A person marked unexplained is where one of those, or the record, does not hold: incomplete penetrance, a new mutation, a misattributed parent or a wrong mode all produce one. The module names only the carriers a mode requires from the generation next to them. It does not estimate the chance that anyone else carries, and a person it does not name may carry the allele.

A correction replaces; a disagreement is kept. The writers write as pedigree, network and medium, so writing a person or a reaction again replaces what the same source wrote and withdraws every conclusion it no longer supports. A fact written under another source is held beside the first. Every conclusion it reaches is drawn from both values, so a person recorded affected by one source and unaffected by another is reasoned about as both, and biology.unsettled() names the person and the field. A second source that writes the same value agrees with the first, and is not named. No query refuses because sources disagree. A family counts each member the mode cannot explain once: a daughter two modes leave unexplained, while two sources give the family’s mode, is one member, not two. A person whose family two sources disagree on is counted in each family a value names.

The calculations are the formulas as written. The Runge–Kutta scripts take fixed steps and are as accurate as the step is small. drift and fixation draw from a fixed generator, so a seed gives the same run every time: a run is a sample, and a single one says little about the chance of fixation. chi_square refuses a count or a share below 0, and logistic and logistic_exact a capacity not above 0 or a population below 0, with ValueError. A class the ratio expects none of adds nothing to a chi-square where none were observed in it, so hardy_weinberg answers a sample of one homozygote, and makes it inf where some were. predator_prey refuses populations that pass the largest real. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

12.1 Kinds and the fields you write

A site’s lat and lon are its latitude and longitude in degrees, and its limit the faintest magnitude its instrument reaches. A star’s ra and dec are its right ascension and declination in degrees, and its mag its magnitude. A night names its site and is the dark time there, and a booking names the site an instrument is booked at and the star it is booked for. An up is a star above a site’s horizon, from its rising to its setting.

A night’s site, a booking’s site and star, and an up’s star and site are written with a window, the stretch of time they hold for. So that a window can be read when it is not now, it is also recorded as two facts that hold at all times: opens and closes for a night, starts and ends for a booking, rises and sets for an up.

Five scripts write these facts for you:

• astronomy.site(name, latitude, longitude, faintest) writes a site under the source sites.
• astronomy.star(name, right_ascension, declination, magnitude) writes a star under the source catalogue.
• astronomy.night(name, where, start, end) writes a night at the site where from start to end, under the source nights.
• astronomy.book(name, where, target, start, end) books the star target at the site where from start to end, under the source bookings.
• astronomy.up(target, where, start) writes the stretch the star target is above the horizon of the site where, under the source ephemeris, named <star>_<site>_<yyyymmdd> by the date of start. It is the first passage that has not ended by start: pass a night’s start to get that night’s passage, which may have begun before it.

Writing a name again corrects it. up() writes nothing for a star that never rises, and for one that never sets it writes the day from start.

12.2 Derived and maintained for you

Three relations are concluded between a star and a site, Circumpolar.s.t for a star s and a site t. astronomy.Circumpolar holds for a star that never sets at the site, astronomy.Hidden for one that never rises, and astronomy.Visible for one that rises, or never sets, and is no fainter than the site’s limit. A site at latitude 0 is read as a northern site.

Observing. A booking is observable only where all three of its premises hold: the booking itself, a night at its site, and an up of its star at its site. The conclusion holds for the stretch where the three overlap, so reading it at a moment inside the booking answers whether the star is up and the night dark then. A star that never rises has no up, and its booking is never observable.

12.3 Queries

import astronomy

astronomy.site("oslo", 59.91, 10.75, 6.0)
astronomy.star("polaris", 37.95, 89.26, 1.98)
astronomy.star("canopus", 95.99, -52.70, -0.74)
astronomy.star("vega", 279.23, 38.78, 0.03)

print(astronomy.circumpolar("oslo"))
print(astronomy.hidden("oslo"))
print(astronomy.day_length(59.91, astronomy.jd(2026, 6, 21.0)))

12.4 What the answers can and cannot mean

The sky is geometry. Circumpolar, hidden and visible are limits of declination set by latitude. They take the horizon to be the geometric one, a level plane through the observer: they allow for no refraction, terrain, twilight, Moon or cloud, and visible compares a star’s magnitude with the site’s limit and nothing else. Rising and setting from up() and rise_set() are the same: for the geometric horizon unless an altitude is given to semi_arc(), and from the sidereal rate. Refraction lifts a body about half a degree, which day_length() includes for the Sun. A star whose declination is exactly on a limit is neither circumpolar nor hidden.

Coordinates are as you supplied them. The module applies no precession, nutation, aberration or proper motion to a star, so its right ascensions and declinations are taken to be for the epoch you want the answer in. Sidereal time is the mean one. A star’s rising and setting are computed for a declination that does not change over the passage.

An observable booking is an overlap, not a promise. observable says that the booking, a night at the site and the star’s time above the horizon overlap. It does not read the star’s magnitude, the site’s limit, the Moon or the weather. window() reports the stretch from the last of the three opening to the first of them closing, and is [] for a booking that never overlaps; it expects the booking to have been written. An up() is for one passage, so a night long enough to hold two of a star’s passages is covered for the first alone, and two calls on the same date for one star and site replace one another.

The sky is written by you. A rising and a setting are facts you write with up(); nothing concludes one from the star and the site alone, and an up already written does not follow a correction to a star’s or a site’s coordinates until you write it again.

A correction replaces; a disagreement is kept. The writers write as sites, catalogue, nights, bookings and ephemeris, so writing a site or a star again replaces what the same source wrote and withdraws every conclusion it no longer supports. A fact written under another source is held beside the first, and every conclusion is drawn from both values: a star recorded at two declinations can be Hidden by one and Visible by the other, and astronomy.unsettled() names the star or the site and the field. No read refuses because sources disagree, except up() and window(). up() needs one value of the star’s right ascension and declination and of the site’s latitude and longitude, and is refused while any has two. window() needs one value of the booking’s start and of its end, and is refused while either has two; unsettled() does not name a booking. observable_at() is not refused: a booking is observable at an instant if any value of it is.

The calculations are the formulas as written. jd() follows Meeus: the Julian calendar before 1582 October 15 and the Gregorian from then, and a date from the ten that calendar dropped is read as Gregorian. A Julian date held as a real steps in about 40 microseconds, so instant() returns the instant of the real rather than of the decimal you wrote. sun() is good to about 0.01 degrees from 1950 to 2050. kepler() stops when a step changes the answer by less than 1e-15, in at most 64 steps, for an eccentricity from 0 up to 1. two_body() takes fixed steps and is as accurate as the step is small: the energy of every orbit it integrates is -0.5, so the change in the energy is the integration’s error. kepler() refuses an eccentricity outside 0 to 1, and takes a mean anomaly past π to within π of 0 first, so it finds E for any M, where 1.0.1 stopped short below -π or a few turns out. gmst() refuses a date so far from 2000 that its angle passes the largest real. An angle is taken modulo 360 degrees by math.fmod first, which is exact, so an angle past a turn loses no digits on its way to radians: past a turn the sine of one is now within a unit or so in the last place, where it was off by a median of 1,251. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

13.1 Kinds and the fields you write

A region’s parent is the name of the region it lies in directly, left unwritten for one that lies in none you record; its level is what kind of region it is, in any word you use; and its colour is the colour a map gives it. A border’s a and b are the names of the two regions it lies between. A place is at latitude lat and longitude lon, north and east positive. A box runs from south to north and from west to east.

Five scripts write these facts for you:

• geography.region(name, parent, level) writes a region under the source regions. Pass "" for a parent not recorded.
• geography.border(a, b) writes a border between two regions, and geography.colour(name, c) the colour a region has, under the source map.
• geography.place(name, lat, lon) and geography.box(name, south, north, west, east) write a place and a box under the source places.

A sixth, geography.paint(palette), writes colours under map for you: it gives each region named in a border the colour that geography.dsatur() chooses, number k as palette[k].

Writing a name again corrects it. Passing "" writes nothing, so it does not withdraw a parent an earlier call recorded: write the parent you mean instead. Record every region, the outermost too, with geography.region: a region is a name that call has recorded, and a parent nobody recorded concludes nothing.

13.2 Derived and maintained for you

Four relations are concluded. geography.Within.r.p holds for each region r and each region p it lies within: its parent, its parent’s parent, and so on. geography.Neighbour.x.y holds both ways round for each border. geography.Clash.x.y holds both ways round for two neighbours the map gives one colour; it is declared so that a map with no clash reads as empty rather than as an unknown kind. geography.Inside.p.b holds for each place p within a box b, the edges included.

A move leaves every region above. Write a region again with another parent and it lies within the new parent’s regions and no longer within the old parent’s, and every holds follows. The conclusions rest on the facts, and withdraw when a fact is corrected.

A box across the antimeridian is read as two ranges. A place is within when its latitude is from the box’s south to its north and its longitude is at or east of the box’s west, or at or west of its east. Longitudes are compared as written, so write them from -180 to 180. A box whose two longitudes are equal is that one meridian, and a box whose south lies north of its north holds no place.

13.3 Queries

import geography

geography.region("norway", "", "country")
geography.region("vestland", "norway", "county")
geography.region("bergen", "vestland", "municipality")
geography.place("bergen_centre", 60.39, 5.32)
geography.box("vestland_box", 59.0, 62.0, 4.5, 8.0)

print(geography.within("bergen"))
print(geography.regions_in("norway", "municipality"))
print(geography.places_in("vestland_box"))
print(geography.haversine(59.91, 10.75, 60.39, 5.32))

13.4 What the answers can and cannot mean

A hierarchy is what you recorded. within and regions_in follow the parents you wrote. The module does not know that a county is larger than a municipality, that two regions overlap or that a region has a border it was not given; a level is a word, and it is compared as one.

A neighbour is a border you wrote. Two regions are neighbours only when a border names them, and the module does not decide from places or boxes that two regions touch. The readers list only regions recorded with a level, so record a region before you read its neighbours or its clashes. dsatur reads the borders alone: it names every region a border names, recorded or not.

A colouring is not the fewest colours. dsatur colours the region whose neighbours already show the most colours, the most neighbours breaking a tie and then the name, and gives it the lowest number none of them shows. No two neighbours share one, but the heuristic does not promise the fewest colours any map needs. paint needs a palette with a colour for every number it chooses; a shorter palette is refused part way, after the colours it reached have been written, so give it a palette as long as the colouring needs, which dsatur shows. dsatur ignores a border from a region to itself.

A place is a point, a box is a rectangle in latitude and longitude. A box is not an area on the ground: its eastern and western edges converge toward a pole, and a box that crosses the antimeridian is read as the two ranges it covers. A place on an edge is within.

The sphere is the mean sphere. haversine, bearing, destination, triangle_area and central_angle treat the Earth as a sphere of radius 6371008.8 metres, so a distance can differ from the ellipsoid’s by a fraction of a percent. vincenty_inverse and vincenty_direct use the WGS84 ellipsoid and are good to well under a millimetre where they converge. They return full-precision numbers and round nothing. Every coordinate and azimuth is taken modulo 360 degrees by math.fmod first, which is exact, so one past a turn loses no digits on its way to radians. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

Some questions have no answer. vincenty_inverse stops after 200 rounds on points that are nearly antipodal, and answers [0.0, 0.0, 0.0, -1.0] rather than a distance; the fourth number is how many rounds it took, and -1.0 means it did not converge. Two points that coincide answer [0.0, 0.0, 0.0, 1.0]. spherical_excess answers 0.0 for three points on one great circle. The Mercator projection has no northing at a pole: do not ask for 90 or -90, where the answer is either a very large number or a refusal, and expect the scale to grow without bound as the latitude nears either pole.

A correction replaces; a disagreement is kept. The writers write as regions, map and places, so writing a region or a place again replaces what the same source wrote and withdraws every conclusion it no longer supports. A fact written under another source is held beside the first. Every conclusion it reaches is drawn from both values, so a region two sources put in two parents lies within both, and a place two sources put at two latitudes is within every box either latitude falls in. geography.unsettled() names the region or the place and the field. A second source that writes the same value agrees with the first, and is not named. No query refuses because sources disagree. A region holds each region within it once: a city two sources put both in its country and directly in its continent lies within the continent by two paths, and the continent holds it once.

14.1 Kinds and the fields you write

A number is named n followed by its value, and its n is the value, at least 1. A candidate names the number it is of, that number’s n and its own k. An operation has an order, how many elements the set has. An element names its op and its label el, and is itself named <operation>_<label>. A cell is one product of the table, a · b = c, named <operation>_<a>_<b>: a, b and c are labels, and left and right name the elements a and b. A triple is three elements in order, named <operation>_<x>_<y>_<z>: x and z are the first and third labels, and xy and yz name the cells x · y and y · z. A triangle has three sides a, b and c in whole units, with c the longest.

Five scripts write these facts for you:

• mathematics.number(v) writes one number and a candidate for each k from 1 to half of it, and mathematics.numbers(lo, hi) every number from lo to hi, under the source numbers. The candidates grow as the square of hi, so write numbers in the hundreds, not the millions.
• mathematics.operation(name, elements, table) writes an operation from its table, table[i][j] being elements[i] · elements[j], under the source table. It writes n² cells and n³ triples for n elements, so it is for tables of a few elements. Give the elements labels without an underscore: the readers split a name at its underscores.
• mathematics.cell(name, a, b, c) rewrites one cell of an operation’s table, so that a · b is c.
• mathematics.triangle(name, x, y, z) writes a triangle from three sides in any order, sorted into a, b and c, under the source figures.

Writing a name again corrects it.

14.2 Derived and maintained for you

Where a property fails, the table names why. noncommuting_pairs names each pair a b whose products differ, nonassociative_triples each three elements x y z whose two bracketings differ, and without_inverse each element that has no inverse. A property that holds is not explained by a list: it is the absence of one.

Everything rests on its facts. A table cell rewritten withdraws the properties that cell held up, and writing the cell back restores them. A divisor is concluded from its candidate’s remainder, which is computed from the number and the candidate.

14.3 Queries

import mathematics

mathematics.numbers(1, 30)
mathematics.triangle("egypt", 3, 4, 5)

print(mathematics.numbers_that_are("perfect"))
print(mathematics.kinds("egypt"), mathematics.gcd(1071, 462))

prints [6, 28], then ['right', 'scalene'] 21.

14.4 What the answers can and cannot mean

A number is as prime as its candidates say. prime asks that no candidate above 1 divide the number, and the candidates are the facts that were written: those number() writes, from 1 to half of the number. A number written by hand with no candidates, and above 1, is concluded prime, whatever it is. The number 1 is neither prime nor composite, has no divisor sum and is deficient. is_prime is a different thing: it computes from its argument, for n up to 3,037,000,499, and reads no fact.

A property of a table is a property of that table. closed, commutative and associative say that no cell or triple of the table breaks them. They do not say what the table means, or that its labels are the set the operation was meant to act on. A triple whose bracket leaves the set has no result to compare, so it is not judged; a table that is not closed can be reported associative because nothing it contains breaks the law, and it is not a group, which asks for both. An element is noninvertible only where the operation has an identity: an operation with none has no element marked either way, and without_inverse is empty.

A triangle has a kind only when its sides close up. Three lengths with a slack of 0, which lie flat, or below it, have none: kinds answers an empty list and area 0.0. isosceles includes the equilateral. The sides are read in order, c the longest, which mathematics.triangle arranges and which sides you write yourself must already be. area refuses a triangle that was not written, and one whose heron passes 9,223,372,036,854,775,807, as for three equal sides of 42,000 units.

A correction replaces; a disagreement is kept. The writing scripts write under the sources numbers, table and figures, so writing a cell or a triangle again replaces its value and withdraws every conclusion that rested on the old one. A value written under another source is held beside the first. Every conclusion it reaches is drawn from both values: a cell given two products breaks commutativity or associativity if either does, and mathematics.unsettled() names the cell. No query refuses because sources disagree.

A divisor sum is not drawn from a divisor bound to it twice. A divisor sum adds every value it reads: a candidate whose k a second source writes, even the same k, would be added twice, and 6 would read as abundant, which no source says. So while a divisor is bound to its number twice, the number is disputed: no divisor sum, perfect, abundant or deficient is concluded for it, numbers_that_are("disputed") names it, and why_not on its divisor sum names the dispute. Forgetting the claim that is not to stand settles it. A candidate whose number two sources disagree on is added to each number a value names, so each of those divisor sums is one source’s.

The calculations are exact in whole numbers and honest at the edge. An int is 64 bits. A result past 9,223,372,036,854,775,807 refuses as an overflow instead of wrapping, so 20! is computed and 21! is refused, F(92) is computed and F(93) is refused. modpow takes a modulus up to 3,037,000,499 so that the product of two remainders fits; binomial refuses only for a coefficient that itself passes the limit. factorize works by trial division, its steps growing as the square root of the second largest prime factor, so a number with two large prime factors takes the longest. The reals are ordinary double-precision arithmetic: solve reads a matrix as singular only when a pivot is exactly 0, so a nearly singular one, as a Hilbert matrix is, answers with the rounding it suffers. A value script has no inputs but its arguments and reads nothing from the store. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

15.1 Kinds and the fields you write

A stratum names the study it belongs to, and gives the successes and the trials of arm A and of arm B. A study is folded from its strata. A screen is a screening test: its prevalence is how common the condition is among those screened, its sensitivity the chance a positive result is given to someone who has it and its specificity the chance a negative result is given to someone who does not, each from 0 to 1. A significance is a test result, with its p and the level alpha it is held to.

Three scripts write these facts for you:

• statistics.stratum(study, name, a_yes, a_n, b_yes, b_n) writes the stratum named <study>_<name> and the study it belongs to, under the source strata.
• statistics.screen(name, prevalence, sensitivity, specificity) writes a screen under the source screens.
• statistics.significance(name, p, alpha) writes a test result under the source tests.

Writing a name again corrects it.

15.2 Derived and maintained for you

Simpson’s paradox. paradox is concluded for a study when its pooled comparison reverses what every stratum shows: arm B ahead in the pool and arm A ahead in every stratum, or the other way round. A stratum in which the arms are level, or in which the arm ahead in the pool is also ahead, is not a reversal, and a stratum with no trials has no rate and does not stand in the way. The conclusion answers why, and withdraws when a count it rests on is rewritten.

Screening. ppv and npv follow from the three figures you wrote and nothing else. A rare condition makes a positive result mostly false even for a good test, which is what mostly_false says.

15.3 Queries

import statistics

statistics.stratum("stones", "small", 81, 87, 234, 270)
statistics.stratum("stones", "large", 192, 263, 55, 80)
statistics.screen("s1", 0.01, 0.9, 0.9)

print(statistics.paradoxes())
print(statistics.pooled("stones"))
print(statistics.predictive_values("s1"))
print(statistics.birthday(23))

prints ['stones'], [0.78, 0.8257142857142857], [0.08333333333333336, 0.9988789237668162] and 0.5072972343239855.

15.4 What the answers can and cannot mean

A reversal is a fact about the counts, not a verdict. paradox says that the pooled comparison and the strata’s disagree. Which one answers the question you asked depends on why the arms were tried in different proportions, which the counts do not say.

A rate needs a trial. A stratum with no trials has no rate, and pooled() and predictive_values() refuse where the rate they read is absent. A script given a list too short for it refuses with a division by zero: a variance needs two values, a mean one, and a regression two different values of x.

A screen is judged at its prevalence. ppv and npv hold for people drawn from the population the prevalence describes. The same test has another ppv among people more likely to have the condition.

A significance is a comparison. significant compares the p you wrote with the alpha you wrote. The module does not compute the p, correct it for many tests, or say whether an effect is large enough to matter.

Nothing checks the figures you write. A probability outside 0 to 1, or a success count above its trials, is a fact like any other. The value scripts are another matter: binom_pmf, binom_cdf, poisson_pmf, bayes, chi_square, stirling_error and deviance refuse a figure outside the range their table names with ValueError, rather than answer a number no probability could be.

A correction replaces; a disagreement is kept. The writers write as strata, screens and tests, so writing a name again replaces what the same source wrote and withdraws every conclusion it no longer supports. A fact written under another source is held beside the first, and every conclusion is drawn from both values: a screen with two prevalences can be mostly false by one and not by the other, and statistics.unsettled() names the fact. No read refuses because sources disagree, except pooled() and predictive_values(), which read one value.

A pooled count is not drawn from a stratum bound to it twice. The pooled counts are sums, and a sum adds every value it reads: a stratum whose successes a second source writes, even the same number, would be counted twice, 354 successes in 350 trials, and a paradox both sources show would vanish. So while a stratum is bound to its study twice by one of its four counts, that count is disputed and not pooled, and neither is what rests on it, the rate and the paradox; a count both sources agree on is still pooled. disputed_studies() names the study, pooled() refuses it, and why_not on the pooled count names the dispute. A stratum with no value of a count adds nothing to it and hides no dispute. Forgetting the claim that is not to stand settles it. A stratum whose study two sources disagree on counts in each study a value names, so each of those pools is one source’s.

The calculations are the formulas as written, kept in range. The variance is Welford’s single pass, so it can differ from a two-pass variance in the last digits; the normal distribution function is erfc correctly rounded, which keeps its digits in the tails; and the quantile is found by 200 halvings and is exact to the last digit of the distribution function. Where a sum or a square in the work would pass the largest real while the statistic does not, as in the mean of 1e308 and 1e307, the values are scaled by a power of two first, which changes no digit of an answer that stays in range. binom_pmf is the product C(n, k) p^k (1 - p)^(n - k) wherever its factors are normal reals, the power of 1 - p corrected for the rounding of 1 - p, and poisson_pmf the running product from e^-lam, which is for a rate to about 708. Past them, each is Catherine Loader’s saddle-point form, through stirling_error, deviance and exact_product, so every probability that is a real is had, at any n or rate: binom_pmf(1100, 550, 0.5) is 0.0240… and poisson_pmf(1000, 1000.0) is 0.0126…. Measured against exact rational arithmetic, the binomial’s product is within 17 units in its last digit to n of 5,000, Poisson’s within 50, and Loader’s form, the looser, within 6 (25 + |ln P|) of them for a probability P. The generator is the module’s own, since DKE Python has no random module, and a run from the same seed repeats exactly: a seed of 0 stays 0, and a seed from 1 to 2147483646 is the one it is meant for. The points of monte_carlo_pi count against the memory one run may hold, so n is for the thousands: 10,000 points from seed 1 give 3.1344, and a run on the service refuses at 20,000.

16.1 Kinds and the fields you write

A station’s coldest and warmest are the mean temperatures of its coldest and warmest months, annual_temp its annual mean and rain its annual rainfall. summer_share is the fraction, from 0 to 1, of that rain which falls in the half of the year when the sun is high. boundary is the coldest-month temperature that divides the temperate group from the continental: 0.0 or -3.0, as the version of the system you follow has it. A storm’s wind_mph is its sustained wind in whole miles per hour. A mineral’s hardness is a number on a scale on which a harder mineral scratches a softer one. A pair is two minerals in order, named <first>__<second>.

Three scripts write these facts for you:

• earthscience.station(name, coldest, warmest, annual_temp, rain, summer_share, boundary) writes a station under the source stations.
• earthscience.storm(name, wind_mph) writes a storm under the source storms.
• earthscience.minerals(names, hardness) writes each mineral, and a pair for each ordered two different minerals, under the source minerals. The pairs grow as the square of the number of minerals.

Writing a name again corrects it.

16.2 Derived and maintained for you

Five groups, one each. The rules test the polar group first and the arid second, and only a station that is neither is tropical, temperate or continental, so a station whose facts are all written is in exactly one. The why_not of a group names the premise that failed: why_not of a desert station’s tropical says that the station is dry.

Two versions of the system. A station whose coldest month falls between -3 and 0 degrees is continental by one version and temperate by the other. boundary is the version you follow, and is written with the station.

16.3 Queries

import earthscience

earthscience.station("manaus", 26.0, 28.0, 27.0, 2300.0, 0.5, 0.0)
earthscience.station("cairo", 14.0, 29.0, 22.0, 25.0, 0.5, 0.0)
earthscience.storm("a", 157)

print(earthscience.climate("manaus"), earthscience.climate("cairo"))
print(earthscience.category("a"))
print(earthscience.quake_ratio(6.0, 7.0))

prints A BW, 5 and 31.622776601683793.

16.4 What the answers can and cannot mean

The groups are Köppen’s first letters, and the sources’ own limits. The module concludes the five groups and the two kinds of arid and polar climate. It does not conclude the finer climates inside A, C and D, which depend on which season is dry or how warm the summer is. A station on a limit falls to one side: a warmest month of exactly 10 degrees is not polar, rain of exactly the threshold is not dry, a coldest month of exactly 18 is tropical and one of exactly the boundary is continental. The sources leave the exact values 0 and 10 degrees between their words “above” and “below”, and the module’s rule is the one stated here.

The high-sun half-year is yours to say. summer_share is the fraction of the rain falling in the half of the year when the sun is high, whichever hemisphere the station is in. The module does not read the hemisphere, and a fraction written for the wrong half classifies the station by it.

A storm is judged by its wind alone. The category is the Saffir-Simpson scale’s five bands of sustained wind, and a wind under 74 has none. The module reads no pressure, surge, size or rainfall.

A mineral scratches by its number. scratches compares two numbers you wrote. Whether a mineral of hardness 7 does scratch one of hardness 3 is the scale’s claim, and two minerals of equal hardness scratch neither.

A formula holds over its range. The calculations check their arguments only where a refusal is the answer: dew_point refuses a humidity that is not above 0 and at most 100. The Magnus dew point was fitted for -40 to 50 degrees; the heat index for 80 degrees Fahrenheit and 40% or more, and below that it returns a value that means little; the wind chill is defined for air at 50 degrees Fahrenheit or colder and a wind above 3 miles per hour; the pressure and temperature by height hold in the troposphere, to about 11,000 metres; and the lifting condensation level is accurate to about 1%. The age of a sample assumes no daughter atoms at the start and none gained or lost since. The energy of an earthquake is for the surface-wave magnitude, and a whole step of magnitude is about 32 times the energy. Where a step of a value script’s work would pass the largest real or fall below the smallest normal one while its value would not, the script works it so that it stays in range, which changes no digit of an answer whose work stays in range.

A correction replaces; a disagreement is kept. The writers write as stations, storms and minerals, so writing a name again replaces what the same source wrote and withdraws every conclusion it no longer supports. A fact written under another source is held beside the first, and every conclusion is drawn from both values: a station recorded with two annual rainfalls can be in two groups, groups() names both, climate() reads the first of them, and earthscience.unsettled() names the station and the field. No read refuses because sources disagree, except dryness_threshold() and category(), which read one value and refuse while two are in force, as a station with two annual means or a storm with two winds in two categories gives them.

17.1 Kinds and the fields you write

A code is named by you, and its name holds no underscore. A word is named <code>_<bits>, with the code it belongs to in code, the string of 0 and 1 in bits, and 2 to the minus its length in weight. A pair is two words of a code in order, named <code>_<first>_<second>, and prefix is True where the first is the beginning of the second, or the same word.

One script writes these facts for you:

• computing.code(name, words) writes the code, a word for each of words and a pair for each two different positions of the list, under the source code. The pairs grow as the square of the number of words.

Writing a name again corrects it. It does not remove a word written before: a corrected code is written under a new name.

17.2 Derived and maintained for you

The conclusions are positive. A code whose Kraft sum is not 1 has no complete rather than a false one, and a code with a word that begins another has no prefix_free. The why_not of prefix_free names the pair that breaks it. A word written twice is one word that begins itself, so the code is not prefix-free, and its weight counts once in the sum.

17.3 Queries

import computing

computing.code("good", ["0", "10", "110", "111"])
computing.code("bad", ["0", "01", "11"])

print(computing.prefix_free_codes())
print(computing.kraft_sum("good"), computing.kraft_sum("bad"))
print(computing.breaking_pairs("bad"))
print(computing.crc32("123456789"))

prints ['good'], 1.0 1.0, ['0 01'] and 3421780262.

17.4 What the answers can and cannot mean

A Kraft sum of 1 is not a prefix code. Both codes in the example have a sum of 1, and only the first is prefix-free. The sum is a property of the lengths, and says only whether a code with those lengths could exist: over 1, none could, and oversubscribed says so. Under 1 or at 1 a code can still have a word that begins another, which prefix_free and breaking_pairs report.

A code is judged by the words written for it. A code with no word has a Kraft sum of 0 and is prefix-free, since no pair breaks it. The module does not check that a word is a string of 0 and 1, or that a code’s name holds no underscore, which breaking_pairs() relies on to split a pair’s name.

A bound is a limit of the answer. to_base and from_base hold numbers of up to 63 binary digits, an int. binary_search makes at most 64 halvings. dijkstra gives a node it does not reach the distance 1000000, so a path is shorter than that, and it needs weights from 0 up; it makes n rounds. A Huffman code is built with at most one fewer merge than there are symbols, the lower index first on a tie, so the lengths are those of one Huffman code and not the only one.

The checksums are the catalogue’s. crc32 is CRC-32/ISO-HDLC and gives 0xcbf43926 for "123456789"; adler32 gives 0x11e60398 for "Wikipedia". Both take each character as a byte, and a character with a code above 255 is not one. Luhn’s check and the ISBN-13 check say whether the digits are consistent, not whether the number was issued. Hamming(7,4) corrects any single flipped bit and decodes two flipped bits wrongly, because it cannot tell.

A correction replaces; a disagreement is kept. computing.code writes as code, so writing a word of a name again replaces what the same source wrote. A fact written under another source is held beside the first, and every conclusion is drawn from both values; computing.unsettled() names the fact. No read refuses because sources disagree, but kraft_sum.

A Kraft sum is not drawn from a word bound to it twice. A word’s weight is written as data, and a sum adds every value it reads: a word whose weight a second source writes, even the same weight, would be counted twice, a sum no source gives, and a code complete by every source would read as oversubscribed. So while a word is bound to its code twice, the code is disputed: no Kraft sum, complete or oversubscribed is concluded for it, disputed_codes() names it, kraft_sum() refuses it, and why_not on its Kraft sum names the dispute. A word with no weight adds nothing and hides no dispute. Forgetting the claim that is not to stand settles it. A word whose code two sources disagree on counts in each code a value names, so each of those Kraft sums is one source’s.

18.1 Kinds and the fields you write

A year is named y<number>, the letter y and its number. A reform is named for the place that adopted it, and its last and first are dates, each written year * 10000 + month * 100 + day: 4 October 1582 is 15821004. Its last_count and first_count are the same two days as day numbers of the Julian calendar. A day is named by you, and its ymd is a date the same way.

Four scripts write these facts for you:

• calendars.years(first_year, last_year) writes a year for each number from the first to the last inclusive, under the source years.
• calendars.year(n) writes the one year y<n>.
• calendars.reform(name, last_year, last_month, last_day, first_year, first_month, first_day, source) writes a reform, with its two counts, under the source you pass.
• calendars.day(name, y, m, d) writes a day under the source days.

Writing a name again corrects it. Writing a reform again under another source holds the rival value beside the first.

18.2 Derived and maintained for you

Two rules reach one conclusion, and a year that fails has no value. gregorian_leap is concluded by either of two rules, so a year divisible by 4 and not by 100 and a year divisible by 400 are both leap years. A year that is not one has no gregorian_leap at all, and the why_not of it names the remainders that failed. differ is concluded from that absence.

A day in a gap is marked, not dropped. The module concludes the relation Gap, between a day and a reform, for each day that falls after the reform’s last day of the old calendar and before its first day of the new. The day stays a valid fact, and a reform’s first rewritten moves the gap and withdraws the marks that rested on it.

18.3 Queries

import calendars

calendars.years(1895, 1905)
calendars.reform("rome", 1582, 10, 4, 1582, 10, 15, "Inter gravissimas")
calendars.day("d1", 1582, 10, 10)

print(calendars.years_that_differ())
print(calendars.skipped("rome"), calendars.missing("d1", "rome"))
print(calendars.weekday(2026, 11, 9), calendars.easter(2026))

prints [1900], [10] True, and 1 [4, 5].

18.4 What the answers can and cannot mean

A year you have not written is not a year that is not a leap year. The rules reach the years in the store, so gregorian_leap(2000) is False while 2000 is not written, and True once it is. The calculations, is_gregorian_leap and month_length among them, answer for any year.

The date values are Gregorian throughout. datetime and duration count in the proleptic Gregorian calendar, and no reform’s gap is in them: a day inside a reform’s gap is a valid datetime, and the rules are what say that a place never had it. The range is years 1 to 9999. A day is 86,400 seconds and a leap second has no place in a datetime, which is a UTC instant written with a trailing Z. A duration has days, hours, minutes and seconds and no months or years, since neither has a fixed number of seconds; a month is calculated with month_length.

Some inputs are not checked. weekday, month_length and julian_month_length do not check that the date exists, and weekday of 30 February answers a weekday. date_exists asks first. easter is the Western date for years from 1583, and answers a date for an earlier year that is no historical Easter.

A span has a limit. span refuses a time of more than about 292 years, and after refuses a result outside years 1 to 9999. Measure a longer time in days with day_number.

A reform’s days are counted on one calendar. The module counts a reform’s skipped days from the two Julian day numbers it writes, so the count holds across the end of a month. The Julian day number’s zero is not day_number’s; only the difference of two means anything.

A correction replaces; a disagreement is kept. calendars.reform writes as the source you pass, so writing a reform again under the same source replaces it, and under another source holds it beside the first. Every conclusion is drawn from both values, a day is in a gap if it is in it under any value in force, and calendars.unsettled() names the fact. No read refuses because sources disagree.

19.1 Kinds and the fields you write

A pair is named by you. Its fg is the relative luminance of the text and its bg that of the background, each from 0.0 for black to 1.0 for white; luminance_hex and luminance give one from a colour. A ray is named by you. Its n1 is the refractive index of the medium it leaves, n2 of the medium it meets, each 1 or more, as every medium’s is for visible light, and sin_i the sine of its angle of incidence, from 0.0 to 1.0.

Two scripts write these facts for you:

• colour.pair(name, text, background) writes a pair under the source pairs.
• colour.ray(name, from_index, into_index, sine_of_incidence) writes a ray under the source rays.

Writing a name again corrects it. To hold a second reading beside the first, write the field yourself with update under another source.

19.2 Derived and maintained for you