From: Thomas Walker Lynch Date: Wed, 11 Feb 2026 06:27:28 +0000 (+0000) Subject: docs X-Git-Url: https://git.reasoningtechnology.com/sitemap.xml?a=commitdiff_plain;h=d7a27f1571fe7b3cc0ab8a2c8c0fee28e999d7aa;p=Epimetheus%2F.git docs --- diff --git a/developer/authored/TM_module.c b/developer/authored/TM_module.c index 0ca7c54..abf3a9a 100644 --- a/developer/authored/TM_module.c +++ b/developer/authored/TM_module.c @@ -42,7 +42,7 @@ self->head_ptr += sizeof(Element); */ -typedef struct { +typedef struct{ PyObject_HEAD PyObject* tape_obj; /* The Container */ void* head_ptr; /* Generic Pointer to Current Item */ @@ -139,6 +139,26 @@ static PyObject* TM·Arr·LsR(TM·Head* self){ Py_RETURN_NONE; } +/* --- PRIMITIVES: ENTANGLEMENT --- */ + +static PyObject* TM·Arr·e(TM·Head* self){ + /* Create a new object of the same type */ + PyTypeObject* type = Py_TYPE(self); + TM·Head* new_tm = (TM·Head*)type->tp_alloc(type, 0); + if (!new_tm) return NULL; + + /* Share the tape */ + new_tm->tape_obj = self->tape_obj; + Py_INCREF(new_tm->tape_obj); + + /* Copy the pointers (Entangled start at same position) */ + new_tm->start_ptr = self->start_ptr; + new_tm->end_ptr = self->end_ptr; + new_tm->head_ptr = self->head_ptr; + + return (PyObject*)new_tm; +} + /* --- PRIMITIVES: I/O --- */ static PyObject* TM·Arr·r(TM·Head* self){ @@ -161,11 +181,17 @@ static PyObject* TM·Arr·w(TM·Head* self, PyObject* val){ static PyObject* TM·Arr·qR(TM·Head* self){ /* GCC Extension: void* comparison and arithmetic */ - return (self->head_ptr >= self->end_ptr - sizeof(PyObject*)) ? Py_True : Py_False; + if(self->head_ptr >= self->end_ptr - sizeof(PyObject*)){ + Py_RETURN_TRUE; + } + Py_RETURN_FALSE; } static PyObject* TM·Arr·qL(TM·Head* self){ - return (self->head_ptr <= self->start_ptr) ? Py_True : Py_False; + if(self->head_ptr <= self->start_ptr){ + Py_RETURN_TRUE; + } + Py_RETURN_FALSE; } @@ -239,6 +265,7 @@ static PyObject* TM·Arr·Lesd(TM·Head* self){ static PyMethodDef Table·SR·ND[] = { {"s", (PyCFunction)TM·Arr·s, METH_NOARGS, ""}, {"sn",(PyCFunction)TM·Arr·sn,METH_VARARGS,""}, + {"e", (PyCFunction)TM·Arr·e, METH_NOARGS, ""}, {"r", (PyCFunction)TM·Arr·r, METH_NOARGS, ""}, {"w", (PyCFunction)TM·Arr·w, METH_O, ""}, {"qR",(PyCFunction)TM·Arr·qR,METH_NOARGS, ""}, @@ -249,6 +276,7 @@ static PyMethodDef Table·SR·ND[] = { static PyMethodDef Table·SL·ND[] = { {"s", (PyCFunction)TM·Arr·s, METH_NOARGS, ""}, {"sn",(PyCFunction)TM·Arr·sn,METH_VARARGS,""}, + {"e", (PyCFunction)TM·Arr·e, METH_NOARGS, ""}, {"ls",(PyCFunction)TM·Arr·ls,METH_NOARGS, ""}, {"lsn",(PyCFunction)TM·Arr·lsn,METH_VARARGS,""}, {"r", (PyCFunction)TM·Arr·r, METH_NOARGS, ""}, @@ -264,6 +292,7 @@ static PyMethodDef Table·SL·ND[] = { static PyMethodDef Table·SR·SO[] = { {"s", (PyCFunction)TM·Arr·s, METH_NOARGS, ""}, {"sn",(PyCFunction)TM·Arr·sn,METH_VARARGS,""}, + {"e", (PyCFunction)TM·Arr·e, METH_NOARGS, ""}, {"r", (PyCFunction)TM·Arr·r, METH_NOARGS, ""}, {"w", (PyCFunction)TM·Arr·w, METH_O, ""}, {"d", (PyCFunction)TM·Arr·d, METH_NOARGS, ""}, @@ -277,6 +306,7 @@ static PyMethodDef Table·SR·SO[] = { static PyMethodDef Table·SL·SO[] = { {"s", (PyCFunction)TM·Arr·s, METH_NOARGS, ""}, {"ls",(PyCFunction)TM·Arr·ls,METH_NOARGS, ""}, + {"e", (PyCFunction)TM·Arr·e, METH_NOARGS, ""}, {"r", (PyCFunction)TM·Arr·r, METH_NOARGS, ""}, {"w", (PyCFunction)TM·Arr·w, METH_O, ""}, {"d", (PyCFunction)TM·Arr·d, METH_NOARGS, ""}, @@ -312,7 +342,6 @@ static PyObject* TM·Nat·sn(TM·Nat* self, PyObject* args){ } static PyObject* TM·Nat·ls(TM·Nat* self){ - /* FIXED: Indentation warning */ if(self->state > 0) self->state--; Py_RETURN_NONE; } @@ -323,8 +352,14 @@ static PyObject* TM·Nat·w(TM·Nat* self, PyObject* val){ PyErr_SetString(PyExc_TypeError, "Cannot write to Abstract Natural Number tape."); return NULL; } + static PyObject* TM·Nat·qR(TM·Nat* self){ Py_RETURN_FALSE; } -static PyObject* TM·Nat·qL(TM·Nat* self){ return (self->state == 0) ? Py_True : Py_False; } +static PyObject* TM·Nat·qL(TM·Nat* self){ + if(self->state == 0){ + Py_RETURN_TRUE; + } + Py_RETURN_FALSE; +} static PyMethodDef TM·Nat·methods[] = { {"s", (PyCFunction)TM·Nat·s, METH_NOARGS, ""}, diff --git a/developer/authored/TM_tutorial.py b/developer/authored/TM_tutorial.py new file mode 100755 index 0000000..3af9f14 --- /dev/null +++ b/developer/authored/TM_tutorial.py @@ -0,0 +1,101 @@ +#!/usr/bin/env python3 +import TM +import sys + +def print_tape(tm): + """ + Prints tape contents using the First/Rest pattern and vertical comma format. + """ + # Reset head to start + tm.LsR() + + if tm.qR() and tm.qL(): + # Handle single element or empty case (qL returns true at start) + # Check if we have at least one element by trying to read? + # Actually qL and qR being true means 1 element or 0? + # qL=True (at start). qR=True (at end). => 1 element. + # We rely on 'r' to throw/work. + try: + print(tm.r()) + except: + print("(empty)") + return + + # FIRST + sys.stdout.write(f"{tm.r()}") + + # REST + while not tm.qR(): + tm.s() + sys.stdout.write(f" ,{tm.r()}") + print("") + +def tm_loops_tutorial(): + print("--- 1. The Standard Traversal (Read -> Process -> Step) ---") + data = [10, 20, 30, 40, 50] + tm = TM.TM_Arr_SR_ND(data) + + while True: + val = tm.r() + print(f"Processing: {val}") + if tm.qR(): break + tm.s() + + print("\n--- 2. The Accumulator (Initialized First) ---") + tm = TM.TM_Arr_SR_ND([1, 2, 3, 4, 5]) + + total = tm.r() # Process First + while not tm.qR(): # Guard + tm.s() # Step + total += tm.r() # Process Next + + print(f"Total: {total}") + + print("\n--- 3. Destructive Filter (Entangled Copy) ---") + # We use TM_ArrV_SR_SO because we need 'd' (delete). + # We added 'e' (entangle) to the SO table to support this specific workflow. + original_data = [1, 2, 3, 4, 5, 6, 7] + tm_master = TM.TM_ArrV_SR_SO(original_data) + + # Create an entangled copy for the deletion work + tm_worker = tm_master.e() + + # Work on the worker + while True: + val = tm_worker.r() + + if val % 2 != 0: + print(f"Deleting odd: {val}") + # Unguarded delete: We must guarantee we don't delete the final cell + # in a way that breaks the invariant for the *other* machine if it were + # elsewhere. But here they are entangled. + # Note: If we delete the last element, the C logic steps back. + tm_worker.d() + + # Since d() is in-place, the 'next' element slides into the current spot. + # We do NOT step. But we must check if we hit the end of the tape + # (i.e. we deleted the tail and stepped back, or the tape is empty). + + # Safety check for end of tape after delete + if tm_worker.qR(): + # We are at the right edge. Check if the current (last) element + # also needs deleting. + val = tm_worker.r() + if val % 2 != 0: + print(f"Deleting last odd: {val}") + try: + tm_worker.d() + except RuntimeError: + print("(Tape became empty)") + break + break + else: + print(f"Keeping even: {val}") + if tm_worker.qR(): break + tm_worker.s() + + print("Final Tape Content:") + print_tape(tm_master) + +if __name__ == "__main__": + tm_loops_tutorial() diff --git a/developer/authored/build/temp.linux-x86_64-cpython-311/TM_module.o b/developer/authored/build/temp.linux-x86_64-cpython-311/TM_module.o index 01ea411..d4993d1 100644 Binary files a/developer/authored/build/temp.linux-x86_64-cpython-311/TM_module.o and b/developer/authored/build/temp.linux-x86_64-cpython-311/TM_module.o differ diff --git a/document/TM_reference.html b/document/TM_reference.html new file mode 100644 index 0000000..83b3073 --- /dev/null +++ b/document/TM_reference.html @@ -0,0 +1,283 @@ + + + + + TM Reference + + + + + + + + + + + + + + + + + + + + +

Machine names

+ +

Concrete first order machines

+ + + TM_<CONTAINER>_<TRAVERSAL>_<ENTANGLEMENT> + + +

CONTAINER

+ + + +

TRAVERSAL

+ + + +

ENTANGLEMENT

+ + + +

Abstract machines

+ + + TMA_<ABSTRACT_NAME> + + +

+ Abstract machines do not bind to a data object. + They are placeholders for virtual tapes and for higher order machinery. +

+ +

Command language grammar

+ +

Command groups

+ + + command_group := [view] command {arg} + view := "L" + command := "e" | "q" | "r" | "s" | "w" | "d" | "a" + arg := "R" | n + + +

+ A method name is a sequence of command groups. + Each command letter begins a new group. + Argument descriptors attach to the command group that precedes them. +

+ +

Mirror view mapping

+ +

+ The command language uses L to select mirror view. + The Python API uses explicit left method names. + The mapping is: +

+ + + +

Traversal and repetition

+ +

+ On SR machines, sn(n) expects a non negative integer. + On SL machines, sn(n) accepts a signed integer, where negative counts step left. +

+ +

Primitive method availability

+ +

+ The second column uses machine name patterns. + The wildcard * stands for any container. +

+ +

Navigation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodAvailable on
s()TM_*_SR_* ,TM_*_SL_*
sn(n)TM_*_SR_* ,TM_*_SL_*
sR()TM_*_SR_* ,TM_*_SL_*
ls()TM_*_SL_*
lsn(n)TM_*_SL_*
lsR()TM_*_SL_*
+ +

Read and write

+ + + + + + + + + + + + + + + + + + +
MethodAvailable on
r()TM_*_SR_* ,TM_*_SL_*
w(v)TM_*_SR_* ,TM_*_SL_*
+ +

Queries

+ + + + + + + + + + + + + + + + + + +
MethodAvailable on
qR()TM_*_SR_* ,TM_*_SL_*
lqR() mirror rightmostTM_*_SL_*
+ +

Entanglement

+ + + + + + + + + + + + + + +
MethodAvailable on
e()TM_*_*_ND ,TM_*_*_EA
+ +

Structural mutation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodAvailable on
d() delete currentTM_*_*_SO ,TM_*_*_EA
dn(n) delete current repeatedTM_*_*_SO ,TM_*_*_EA
dR() cue delete to rightmostTM_*_*_SO ,TM_*_*_EA
ld() mirror delete currentTM_*_SL_SO ,TM_*_SL_EA
ldn(n) mirror delete repeatedTM_*_SL_SO ,TM_*_SL_EA
ldR() cue delete to leftmostTM_*_SL_SO ,TM_*_SL_EA
esd() entangle, step, delete neighborTM_*_*_EA
esdn(n) repeated neighbor deleteTM_*_*_EA
esdR() cue neighbor delete to rightmostTM_*_*_EA
lesd() mirror neighbor deleteTM_*_SL_EA
a(v) insert one valueTM_*_*_SO ,TM_*_*_EA
an(list) insert list valuesTM_*_*_SO ,TM_*_*_EA
+ + + + + + + diff --git a/document/TM_sav.html b/document/TM_sav.html new file mode 100644 index 0000000..13555e3 --- /dev/null +++ b/document/TM_sav.html @@ -0,0 +1,681 @@ + + + + + Tape Machine + + + + + + + + + + + + +

Introduction

+ +

+ A Tape Machine (TM) is an abstract mechanism for manipulating data found in sequences. Such sequences include lists, arrays, sets (given an ordering function), and maps (also given an ordering function). Also included are linear traversals of more complex structures. The theory underpinning the TM is discussed in the TTCA book. +

+ +

+ Unlike standard arrays (which are stateless) or iterators (which are transient), a TM combines a data substrate with a persistent head. The head maintains positional state, allowing the programmer to navigate, read, and write tape cells. +

+ +

+ Thus a TM packages both data, and all pointers into that data, within one structure. +

+ +

+ A TM can have a concrete tape or a virtual tape. A concrete tape is backed by a container. A virtual tape presents the same TM interface, but its cells and motion are implemented by functions over some internal state. For example, an abstract Counting Number tape machine can use a big integer as its state and implement stepping and reading over that state, instead of traversing an array of numbers. +

+ +

+ A defining invariant of all Tape Machines is that cell contents are cargo. The TM reads and writes cell payload, but it does not interpret that payload as control. The decisions are made above the TM, by the programmer’s algorithm. +

+ +

+ A TM is constructed with a set of feature symbols that select which parts of the interface are available. When no feature symbols are supplied, the result is a non-destructive step right machine with no indexing. Feature symbols can enable step left behavior (via the mirror view), enable random access indexing functions, and accounting for a shared tape, among other things. +

+ +

+ A first order TM is defined by a single invariant: the head is always on a valid cell. This invariant makes the primitive interface total: every move, read, write, and query has a clean, well defined meaning, and caller code stays free of scattered end case tests. +

+ +

+ If an operation were permitted to remove the last remaining cell of a tape, said first order invariant would be broken and the interface would stop being total. A working TM that supported such a deletion would need status logic that represents the empty state. That status logic would either be embedded inside the TM operations as edge handling, or be represented explicitly as a separate status machine layered above the base TM. Either choice represents a shift in level of analysis being done, and therefore would lead to the construction of a distinct second order tape machine. +

+ +

+ Tape machines that share a tape are said to be entangled. There will be both data and structure hazards among entangled machines. Data hazards have to do with the misuse of locks or other mistakes in cooperation between machines that cause a machine to read the wrong data. Data hazards can lead to incorrectly computed results, but they will not break the machines. In contrast, structure hazards lead to broken machines. The principle structure hazard is that of one entangled TM deleting a cell that another TM has its head on. That orphans the head of that other machine and leads to a violation of the a tape machine head is always on a valid cell invariant. +

+ +

+ We leave the data hazard management to the programmer; however, we provide specific features for avoiding structure hazards. + These are selected at TM construction time. In one approach, no methods are placed on the interface that can destroy tape cells. This supports a non-destructive programming paradigm, so such machines are said to be non-destructive. Without destructive operations, entangled machines simply do not have the ability to break each other. In a second approach, the interface is configured so there are no functions for entangling machines in the first place. Each solitary machine can safely perform destructive operations because no other machine shares its tape. As a third approach, each group of entangled machines shares a catalog listing all machines in the group. Caller code can guard operations by querying whether a planned operation is safe before attempting it. This third strategy is called entanglement accounting. During the time of execution of the guard and operation, each tape machine must be able to lockout others from access to the catalog. Yet another approach is for the programmer, compiler, or external function to prove code is safe, which is the same as proving that guard code is not needed. An alternative is to use a compiler that only produces correct code in the first place. This is the approach of correct by construction. +

+ +

Command language

+ +

+ The command language is not used directly, rather it describes the letter patterns used to form TM interface function names. + Such an approach can be found in LISP language list access function names, and its extension is described in the paper "Towards a Better Understanding of CAR, CDR, CADR and the Others". +

+ +

+ The actual function names found on TM interfaces are listed in later sections of this guide. The ultimate authority is the source code itself. Later we can add a compiler for creating new functions based on this language. Such a compiler would be a function that adds functions to a TM interface. +

+ +

+ A TM is constructed with a set of feature symbols that select which parts of the language are available. + When no feature symbols are supplied, the result is a non-destructive step right machine with no indexing. + Feature symbols can enable step left behavior (via the mirror view) and can independently enable indexing commands. +

+ + +

For the non-destructive step right machine

+ +

grammar

+ + statement :: ( command [arg]* )+ + command :: e | q | r | s | w + arg :: R | n + + +

statement

+

+ A statement is parsed left to right. Each command letter begins a new command group. All following arg descriptors attach to that command until the next command letter appears. There are no spaces. Arguments are given to the resulting function in the order that the command and its descriptors require them. +

+ +

+ Accordingly, a function name such as snr(i) denotes two command groups: + sn(i) steps right i times, then r copies out the current cell. +

+ +

command

+ + +

+ Two or more machines are entangled when they share one tape. + Entangle differs from clone because the tape is shared rather than copied. + What is duplicated is the head state, so entangled heads move independently. + A machine produced by e begins with its head on the same cell as the machine it was created from. +

+ +

+ The query command, q, reports head state. + With no arg descriptor it returns a boolean value. + With an R arg descriptor it returns true iff the head is on the rightmost cell. With an I arg descriptor it returns an index. +

+ +

+ TM uses a guard approach for end cases. Query commands appear in control flow so caller code can select the guards it needs and handle end cases explicitly. + When guards are unnecessary, caller code can omit them. +

+ +

+ The r and w commands copy values to and from the current cell. + As of the time of this writing they are cell local operations, so direction does not enter. +

+ +

+ The s step command moves the head to the right neighbor cell. + When s is given an n arg descriptor, it performs n right steps. + On a step right only machine, n must be positive. +

+ +

arg

+ + +

+ The n arg descriptor supplies a repetition count. +

+ +

+ The R arg descriptor focuses the command on the rightmost cell. + For qR, the result is true iff the head is on rightmost. + For sR, the effect is to cue the head to rightmost. +

+ +

Examples

+ +

Relative head movement

+ + s ; step to right neighbor + sn(1) ; step to right neighbor + sn(2) ; step to right neighbor twice + + +

Absolute head movement

+ + sR ; cue the head to rightmost + + +

Query

+ + qR ; true iff head is on rightmost + + +

Copying to and from tape cells and python variables

+ + r ; copies cell contents to the LHS of an assignment + w(v) ; copies v into the cell + + + +

For the non-destructive machine that has step left

+ +

+ The step right grammar extends to left going behavior by introducing a mirror view of a machine. + In the mirror view, every rightward operation corresponds to the base machine’s leftward operation, so new command letters are unnecessary. + What is rightmost in the base view becomes leftmost in the mirror view, and vice versa. +

+ +

+ In this extended grammar, the L prefix selects the mirror view for the command group that follows it. + L affects direction sensitive operations such as stepping, moving to rightmost, and scans. + Today r and w are cell local, so L does not change their behavior. +

+ +

+ Step left support does not imply index space. + A machine can support L while still omitting index operations. + When index space is enabled as an additional feature, the I arg descriptor becomes available and index based cue and query forms become legal. + When L is available, n can also be negative, with the sign selecting the direction in the base view. +

+ +

grammar

+ + statement :: ( [machine] command [arg]* )+ + machine :: L + command :: e | q | r | s | w + arg :: R | I | n + + +

+ Index space, as defined in the TTCA book, is a natural number sequence machine that walks the tape of a base machine and establishes a one to one correspondence between natural numbers and tape cells. + That correspondence belongs to the tape and stays fixed when we change the view. + For example, consider a tape with cells [c_0 ,c_1 ,c_2 ,c_3 ,c_4], where c_4 is rightmost and has index 4. + In the mirror view we write the same cells as [c_4 ,c_3 ,c_2 ,c_1 ,c_0]. + In the mirror view c_4 sits at the left edge, and it still has index 4. + A right step from c_4 in the mirror view lands on c_3, which matches a left step from c_4 in the base view. +

+ +

Examples

+ +

+ In these examples, the comments discuss what happens on the base machine. Effects in the mirror view match the same command without the L prefix. +

+ +

Relative head movement

+ + Ls ; step to left neighbor + Lsn(2) ; step to left neighbor twice + sn(-2) ; step to left neighbor twice + sn(2) ; step to right neighbor twice + + +

Head movement relative to leftmost

+ + sI(0) ; cue the head to the leftmost cell by index + sI(3) ; cue the head to tape[3] + + +

+ LsI(k) and sI(k) cue the head to the same indexed cell. + L flips direction and the meaning of R, not the index to cell correspondence. + Thus LsI(0) cues the cell with index zero, which is rightmost in the mirror view and leftmost in the base view. +

+ +

Absolute head movement

+ + LsR ; cue the head to leftmost + sR ; cue the head to rightmost + + +

+ Without code optimization LsR will be faster than sI(0), because sI requires passing and processing an argument. +

+ +

Query

+ + LqR ; head is on leftmost + qR ; head is on rightmost + qI ; index of the head + qIR ; index of rightmost + LqIR ; index of leftmost, typically zero + + +

+ The I arg descriptor causes q to return an index. + By default q returns a boolean value. + In other commands, an I arg descriptor indicates that an index argument is supplied. +

+ +

+ The R arg descriptor focuses the command on the selected view rightmost cell. + For qR, the result is true iff the head is on rightmost. + For qIR, the result is the index of rightmost. + Under L, that rightmost cell is the base view leftmost cell, so LqIR returns the index of leftmost, typically zero. +

+ +

Copying to and from tape cells and python variables

+ + r ; copies cell contents to the LHS of an assignment + w(v) ; copies v into the cell + + +

+ The current r and w are cell local and are unaffected by L. + If we later support list forms or repetition forms for copy, L will affect the scan direction for those operations. +

+ +

TM interface functions

+ +

+ This section lists the concrete methods exposed by the Python/C implementation. + These methods implement a selected subset of the command grammar. + The grammar defines a command language, while the primitive set defines the operations the library exposes directly. + Later sections can introduce a compile layer that accepts additional command combinations. +

+ +

+ The L prefix is not implemented as a distinct family of primitives. + In the command language it selects the mirror view. + In the API the same effect is provided by explicit left primitives such as ls() and lsn(n), or by allowing a signed n on machines that support step left. +

+ +

Feature symbols and primitive availability

+ +

+ A TM is constructed with feature symbols that select which primitive families are present. + With no feature symbols, the result is a non-destructive step right machine with no indexing. + Enabling step left adds left motion primitives (or signed n support) and mirror view semantics in the command language. + Indexing is an independent feature: when enabled, index based query and cue forms become legal and corresponding primitives become available. +

+ +

Navigation primitives

+ +

+ Navigation primitives implement the s command with the argument forms ε, n, and R. + On a step right only machine, n is constrained to positive values. + On a machine that supports step left, n can be negative, with the sign selecting direction in the base view. +

+ + + +

+ If step left is enabled, left motion is available either as explicit primitives, or via negative n on sn(n), depending on the configured interface. + When explicit left primitives exist, they correspond to the mirror view command forms. +

+ + + +

+ Note the correspondence: sR cues rightmost in the base view, and LsR cues leftmost of that same underlying tape. + The primitives sR() and lsR() are optimized cues. +

+ +

Input and output primitives

+ +

+ The I/O primitives implement r and w(value). + In the command language, r reads the current cell payload, and w(v) writes a payload to the current cell. + As of the time of this writing, these operations are cell local, so mirror view does not change their behavior. +

+ + + +

+ Bulk forms can exist in the API, but they are not represented in the current command grammar. + They are library level conveniences built on top of repeated primitive behavior. + If bulk copy forms become part of the command grammar later, mirror view will affect scan direction for those operations. +

+ + + +

Destructive Primitives

+ +

+ Machines configured with the SO (Solitary) entanglement approach may expose primitives that modify the tape structure. + These are distinct from w (which modifies cell content) because they change the cell count or sequence. +

+ +

+ Note: Not all container types support all destructive operations. For example, ARR (Fixed Array) does not support deletion or insertion, whereas ARRV (Variable Array) does. +

+ +

Delete (d)

+

+ Removes cells from the tape. The head typically lands on the right neighbor of the deleted segment. +

+ + +

Delete Neighbor (esd)

+

+ A compound-style primitive that deletes a neighbor without moving the active head. + Mnemonic: Entangle-Step-Delete (conceptually acts on the neighbor). +

+ + +

Insert/Append (a)

+ + +

Query primitives

+ +

+ Query primitives are built from the q command. + On the step right only machine, the primitive set covers the boolean query forms. + When indexing is enabled as an additional feature, index valued query forms become available. +

+ + + +

+ If indexing is enabled, the API also exposes index query primitives. + These correspond to the I arg descriptor in the command language. +

+ + + +

+ Mirror view query forms follow the same rule in the command language. + For example, LqR tests the leftmost of the underlying tape, and LqIR returns its index, typically zero. +

+ +

Entanglement primitives

+ +

+ Entanglement primitives implement the e command. + The entangled machine shares the tape with the original machine and and initially have their head on the same cell. + In entanglement accounting configurations, entangled machines also share the group catalog used by guard predicates. +

+ + + +

+ Combined command forms such as es are legal in the grammar, but they are not required as primitives. + The library can expose such combinations as convenience calls, or generate them through a compile layer. + The core model remains that a statement is a sequence of commands applied to a selected view. +

+ +

Usage

+ +

First order TM properties

+ +

+ For a first order TM these properties are always true. +

+ +
    +
  1. The head is always on a valid cell.
    2. +
  2. All cells return a value when read.
    3. +
+ +

+ In order to maintain these properties, a TM uses inclusive bounds for intervals, including intervals of cells, and intervals of indexes. +

+ +

Contract with the programmer

+ +

+ Some first order TM types rely upon the caller to maintain a contract. + Such machines typically have debug variants that add contract checks. + For some machines, breaking the contract limits compiler optimization. + For other machines, breaking the contract causes program bugs. +

+ +

+ Contract: +

+ +
    +
  1. When there is a right bound, the caller guarantees that he will never command the machine to step beyond the rightmost cell.
    2. +
  2. When there is a left bound, the caller guarantees that he will never command the machine to step left of the leftmost cell.
    3. +
+ +

+ When traversing a tape, the contract is fulfilled by a First Rest pattern. +

+ +

First Rest pattern with initialization

+ + + # Pattern 1: First Rest (Initialize with First) + # Useful when the accumulator starts with the first value. + total = tm.r() # Process First + while not tm.qR(): # Guard: Is there a Rest? + tm.s() # Step (Protected) + total += tm.r() # Process Next + + +

+ Here tm.qR() queries whether the head is on the selected view rightmost cell. + It guards the step in the loop. + No redundant tests are done, and the loop ends without stepping off the tape. +

+ +

First Rest pattern without initialization

+ +

+ Sometimes the accumulator is initialized to an identity value (such as zero) before the loop starts. + In that form, the loop and a half structure is natural. +

+ + + # Conceptual "do" loop + do: + total += tm.r() # Always process the current cell + if tm.qR() break # protects increment from spilling over + tm.s() # Step only when not at the end + + +

+ Python has no do statement, so the same logic is written explicitly: +

+ + + # Python implementation + while True: + total += tm.r() + if tm.qR(): break + tm.s() + + +

+ The middle test tm.qR() guards tm.s(), so the machine never steps beyond rightmost. +

+ +

Region Machine

+ +

A Region Machine is a composite structure built from three entangled tape machines. It enforces the invariant that the active head remains within a specified closed interval of the tape.

+ +

Structure

+ +

The Region Machine consists of:

+ +

Because the Region Machine relies on the First Order invariant (head always on a valid cell), a region cannot be empty. The minimum region size is one cell, where the Left Boundary, Right Boundary, and Active Head all occupy the same cell.

+ +

Behavior

+ +

The Region Machine implements the standard TM interface but constrains movement based on the boundary heads.

+ + + +

Boundary Management

+ +

The boundaries of a region are themselves Tape Machines. This allows the region to expand or contract dynamically. Moving a boundary head changes the effective range of the Active Machine immediately.

+ +

Safety Constraint: A boundary head cannot step past the other boundary head. The Left Boundary must always be to the left of or on the same cell as the Right Boundary. Furthermore, the Active Head must not be orphaned by boundary movement. If the Right Boundary steps left past the Active Head, the Active Head is no longer valid. Therefore, boundary contraction requires checking or moving the Active Head to maintain the invariant.

+ +

TM Workspace functions

+ +

The TM_workspace namespace contains higher-level functions that coordinate multiple machines. These functions are not part of the core TM interface but operate on TMs to implement common algorithms.

+ +

Tandem operations

+ +

Tandem operations drive multiple machines simultaneously. They are useful for copying, comparing, or parallel processing.

+ + + +

Predicates

+ +

Predicates test relationships between entangled machines.

+ + + + + + + +

Second Order Machine (TMS)

+ +

A Second Order Machine, or TMS (Tape Machine Status), is a wrapper that manages the lifecycle of a First Order Tape Machine. It introduces the concept of status to handle conditions that violate First Order invariants, specifically the absence of valid cells (emptiness).

+ +

Status definitions

+ +

The TMS manages a state machine where the states are called statuses to distinguish them from the internal state of the tape or head. The current status determines which interface functions are available to the programmer.

+ + + +

Dynamic interface dispatch

+ +

The TMS implementation uses dynamic dispatch (or mixin replacement) to enforce status constraints. When the status changes, the interface functions are swapped.

+ +

For example, in the Empty status, the r() function is mapped to an error handler: Error: Attempted to read from an empty machine. This prevents the programmer from accidentally running First Order logic on a machine that does not satisfy the First Order invariant.

+ +

Transitions

+ +

Status changes occur when operations alter the cell count to or from zero, or when the head is explicitly parked or unparked.

+ +

Promotion (Empty to Active)

When a TMS is Empty, calling an insertion function (e.g., append(v)) creates the first cell. The status transitions to Active. The interface is updated to expose standard TM behaviors. The head is placed on the newly created cell.

+ +

Demotion (Active to Empty)

If a deletion operation removes the last remaining cell of an Active machine, the First Order invariant is broken. The TMS detects this event, destroys the underlying First Order TM, and transitions the status to Empty. The interface is updated to the restricted Empty set.

+ +

Usage with algorithms

+ +

Algorithms requiring a First Order TM (such as foreach loops or First Rest patterns) must effectively be guarded by a status check.

+ + if tms.is_active(): # Safe to treat as a First Order TM run_algorithm(tms) else: # Handle empty case pass + +

Because the TMS implements the TM interface, it can be passed directly to these algorithms. However, if the status is Empty, the first operation attempted by the algorithm (usually r()) will trigger a "second order" error, alerting the programmer that they neglected the guard.

+ +

Machine Naming Convention

+ +

+ Concrete Tape Machine classes follow a strict naming grammar. This grammar acts as a feature descriptor, allowing the programmer to select a machine by constructing its name. +

+ +

+ The name is composed of three feature segments: the Container Type, the Step Direction, and the Entanglement Approach. +

+ +

grammar

+ + class_name :: TM [ _container ] [ _direction ] [ _entanglement ] + container :: ARR | ARRV | GR | GLR | SET | MAP | MAPK | MAPV + | ASCII | UTF8 | BCD + direction :: SR | SL + entanglement :: ND | SO | EA + + +

+ Segments are separated by underscores. The default configuration for a segment is used if that segment is omitted. + The default machine is TM_ARR_SR_ND (Fixed Array, Step Right, Non-Destructive). +

+ +

container

+ + +

direction

+ + +

entanglement

+ + +

Abstract and Traversal Machines

+

+ The naming convention extends to Abstract and Traversal machines using specific prefixes. +

+ + + + + + diff --git a/document/TM_user.html b/document/TM_user.html new file mode 100644 index 0000000..62993d5 --- /dev/null +++ b/document/TM_user.html @@ -0,0 +1,226 @@ + + + + + TM User Guide + + + + + + + + + + + + + + + + + + + + +

Introduction

+ +

+ A Tape Machine (TM) is an abstract mechanism for manipulating data found in sequences. + Such sequences include lists, arrays, sets (given an ordering function), maps (given an ordering function), and linear traversals of more complex structures. + The theory underpinning the TM is discussed in the TTCA book. +

+ +

+ Unlike standard arrays (which are stateless) or iterators (which are transient), a TM combines a data substrate with a persistent head. + The head maintains positional state, allowing the programmer to navigate, read, and write tape cells. +

+ +

+ A defining invariant of a first order TM is: + the head is always on a valid cell. + This invariant makes the primitive interface total. + Every move, read, write, and query has a clean, well defined meaning, and caller code stays free of scattered end case tests. +

+ +

Choosing a machine

+ +

+ In the current implementation, you choose a TM by choosing a concrete TM class. + Machine capabilities are encoded in the class name. + Concrete machines require a data object at construction time. + Abstract machines do not require a data object, but they come later. +

+ +

+ The default concrete machine is TM_ARRAY_SR_ND(data_obj). + It treats the data object as a Python array of cell payload pointers. +

+ +

Machine naming convention

+ +

+ First order concrete machines use this name form: +

+ + + TM_<CONTAINER>_<TRAVERSAL>_<ENTANGLEMENT> + + +

+ Abstract machines (virtual tapes) use: +

+ + + TMA_<ABSTRACT_NAME> + + +

Field meanings

+ + + +

Command language

+ +

+ The command language is not used directly. + It describes the letter patterns used to form TM interface method names. + The approach began with LISP, and its extension is described in the paper + "Towards a Better Understanding of CAR, CDR, CADR and the Others". +

+ +

+ A method name is a sequence of command groups. + Parsing is left to right. + Each command letter begins a new group. + Any argument descriptors that follow attach to that group until the next command letter appears. +

+ +

+ Example: snr(i) denotes two groups. + sn(i) steps right i times, then r() reads the current cell. +

+ +

Core commands

+ + + +

Argument descriptors

+ + + +

Mirror view

+ +

+ Some machines support stepping left as well as right. + In the command language, the L prefix selects the mirror view for the command group that follows it. + In the mirror view, rightward operations correspond to leftward operations in the base view. + What is rightmost in the base view becomes leftmost in the mirror view, and vice versa. +

+ +

+ In the Python API, mirror view forms are exposed as explicit left methods, such as ls() for Ls and lsR() for LsR. +

+ +

Entanglement and safety

+ +

+ Tape machines that share a tape are said to be entangled. + There are both data hazards and control hazards among entangled machines. + Data hazards relate to unexpected writes and reads and can lead to incorrect results. + Control hazards can break machines. + The primary control hazard is one machine deleting a cell that another machine is visiting, which violates + a tape machine head is always on a valid cell. +

+ +

+ Entanglement policy is encoded in the machine name: +

+ + + +

Usage patterns

+ +

First Rest pattern with initialization

+ + + # Pattern 1: First Rest (Initialize with First) + # Useful when the accumulator starts with the first value. + total = tm.r() # Process First + while not tm.qR(): # Guard: Is there a Rest? + tm.s() # Step (Protected) + total += tm.r() # Process Next + + +

First Rest pattern without initialization

+ + + while True: + total += tm.r() + if tm.qR(): break + tm.s() + + +

Composite machines

+ +

Region Machine

+ +

+ A Region Machine is a composite built from three entangled tape machines. + It enforces the invariant that the active head stays within a specified closed interval of the tape. +

+ + + +

+ In the command language, the active head is on the left boundary iff LqR is true in the active view. + In the Python API, that corresponds to an explicit left query helper, or to a predicate that tests whether two entangled heads are on the same cell. +

+ +

TM workspace functions

+ +

+ The TM_workspace namespace contains higher level functions that coordinate multiple machines. + These functions are not part of the core TM interface. +

+ +

Second order machine

+ +

+ A second order TM, TMS (Tape Machine Status), is a wrapper that manages the lifecycle of a first order TM. + It introduces explicit status values to represent conditions that violate first order invariants, such as emptiness. +

+ + + + + + +