xbtm 0.1.0__tar.gz

xbtm-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Packaging artifacts
+build/
+dist/
+*.egg-info/
+
+# Test and coverage output
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editor and operating-system files
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+.ruff_cache/

xbtm-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

xbtm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Imagination12357
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xbtm-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: xbtm
+Version: 0.1.0
+Summary: XbTm (X-base Target Mapping) is a tool and DSL for generating canonical, entropy-efficient mappings from an x-way random source to an m-way target choice.
+Project-URL: Repository, https://github.com/Imagination12357/xbtm
+Project-URL: Issues, https://github.com/Imagination12357/xbtm/issues
+Author: Imagination12357
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dsl,entropy,probability,random,random-generation,rejection-sampling
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.0.0
+Description-Content-Type: text/markdown
+
+XbTm (X-base Target Mapping) is a tool and DSL for generating canonical, entropy-efficient mappings from an x-way random source to an m-way target choice.
+
+`xbtm` is a DSL for deterministically exploring and visualizing ways to emulate a uniform random generator with `target` outcomes using one with `base` outcomes.
+
+## DSL format
+
+A complete program combines a header and a body with a colon.
+
+```text
+X{base}T{target}:{body}
+```
+
+`base` and `target` are natural numbers. When `target` is at least 2, `base` must also be at least 2. When `target` is 1, `base` may be 1 because there is no outcome to choose between.
+
+Every body starts at the ordinary state `1`.
+
+```text
+X2T5:1>2>4>8=5|3>6=5|(1)
+```
+
+## States and termination
+
+- `n`: An ordinary, newly visited state `n`, written as a natural number.
+- `(n)`: A reference state that returns to the previously visited state `n`. A reference state terminates the body.
+- `!`: A termination marker indicating that the current ordinary state exactly equals `target`. The implementation represents it as an operator token for convenience.
+
+Thus, a body starts at an ordinary state, repeats transitions, and ends with either a reference state or `!`.
+
+## Transitions
+
+There are two kinds of transition.
+
+### Expand: `>`
+
+```text
+old_state>next_state
+```
+
+`expand` multiplies the current state by `base`.
+
+```text
+next_state = old_state * base
+```
+
+### Split: `=`
+
+```text
+old_state=pxq|r
+old_state=p|r        # when q == 1
+```
+
+`split` divides the current state using `target`.
+
+```text
+p = target
+q = old_state // target
+r = old_state % target
+old_state = p * q + r
+```
+
+Here, `p` and `q` describe the split, and `r` is the next state. When `q` is 1, `x1` is omitted. If the next state `r` was already visited, it is written as `(r)` and the body ends.
+
+When the split has no remainder, it ends with `|!` instead of creating state `0`.
+
+```text
+old_state=pxq|!
+```
+
+For the full DSL rules, see the [DSL specification](https://github.com/Imagination12357/xbtm/blob/main/docs/dsl-spec.md).
+
+## Installation
+
+```bash
+pip install xbtm
+```
+
+## Python usage
+
+```python
+from xbtm import Program, generate
+
+program = generate(2, 5)
+
+print(program.text)
+print(program.get_trials())
+
+same_program = Program.parse("X2T5:1>2>4>8=5|3>6=5|(1)")
+```
+
+## Examples
+
+```text
+X2T8:1>2>4>8!
+X7T8:1>7>49=8x6|(1)
+X1T1:1!
+X4T2:1>4=2x2|!
+```

xbtm-0.1.0/README.md

@@ -0,0 +1,97 @@
+XbTm (X-base Target Mapping) is a tool and DSL for generating canonical, entropy-efficient mappings from an x-way random source to an m-way target choice.
+
+`xbtm` is a DSL for deterministically exploring and visualizing ways to emulate a uniform random generator with `target` outcomes using one with `base` outcomes.
+
+## DSL format
+
+A complete program combines a header and a body with a colon.
+
+```text
+X{base}T{target}:{body}
+```
+
+`base` and `target` are natural numbers. When `target` is at least 2, `base` must also be at least 2. When `target` is 1, `base` may be 1 because there is no outcome to choose between.
+
+Every body starts at the ordinary state `1`.
+
+```text
+X2T5:1>2>4>8=5|3>6=5|(1)
+```
+
+## States and termination
+
+- `n`: An ordinary, newly visited state `n`, written as a natural number.
+- `(n)`: A reference state that returns to the previously visited state `n`. A reference state terminates the body.
+- `!`: A termination marker indicating that the current ordinary state exactly equals `target`. The implementation represents it as an operator token for convenience.
+
+Thus, a body starts at an ordinary state, repeats transitions, and ends with either a reference state or `!`.
+
+## Transitions
+
+There are two kinds of transition.
+
+### Expand: `>`
+
+```text
+old_state>next_state
+```
+
+`expand` multiplies the current state by `base`.
+
+```text
+next_state = old_state * base
+```
+
+### Split: `=`
+
+```text
+old_state=pxq|r
+old_state=p|r        # when q == 1
+```
+
+`split` divides the current state using `target`.
+
+```text
+p = target
+q = old_state // target
+r = old_state % target
+old_state = p * q + r
+```
+
+Here, `p` and `q` describe the split, and `r` is the next state. When `q` is 1, `x1` is omitted. If the next state `r` was already visited, it is written as `(r)` and the body ends.
+
+When the split has no remainder, it ends with `|!` instead of creating state `0`.
+
+```text
+old_state=pxq|!
+```
+
+For the full DSL rules, see the [DSL specification](https://github.com/Imagination12357/xbtm/blob/main/docs/dsl-spec.md).
+
+## Installation
+
+```bash
+pip install xbtm
+```
+
+## Python usage
+
+```python
+from xbtm import Program, generate
+
+program = generate(2, 5)
+
+print(program.text)
+print(program.get_trials())
+
+same_program = Program.parse("X2T5:1>2>4>8=5|3>6=5|(1)")
+```
+
+## Examples
+
+```text
+X2T8:1>2>4>8!
+X7T8:1>7>49=8x6|(1)
+X1T1:1!
+X4T2:1>4=2x2|!
+```

xbtm-0.1.0/docs/dsl-spec.md

@@ -0,0 +1,168 @@
+# XbTm DSL specification
+
+This document is the normative specification for XbTm programs. Future parsing and validation must conform to this document; the current implementation may not yet support every rule below.
+
+## 1. Lexical rules
+
+Whitespace is not permitted. A **natural number** is a non-zero decimal integer:
+
+```text
+natural ::= [1-9][0-9]*
+```
+
+The literal `x` is the DSL multiplication marker. In mathematical equations in this document, multiplication is written with `*`.
+
+## 2. Program syntax
+
+```text
+program              ::= header ":" body
+header               ::= "X" natural "T" natural
+body                 ::= "1" { ordinary_transition } terminal
+
+ordinary_transition  ::= ">" natural
+                        | "=" natural [ "x" natural ] "|" natural
+
+terminal             ::= "!"
+                        | ">" reference
+                        | "=" natural [ "x" natural ] "|" reference
+                        | "=" natural "x" natural "|" "!"
+
+reference            ::= "(" natural ")"
+```
+
+The grammar describes the character-level shape only. The semantic constraints in the next sections determine whether a syntactically valid program is well-formed.
+
+## 3. Header constraints
+
+Let `B` be the `base` value from `X{B}` and `T` be the `target` value from `T{T}`.
+
+- `B` and `T` are natural numbers.
+- If `T >= 2`, then `B >= 2`.
+- `T = 1` permits `B >= 1`; it represents a target with no choice between outcomes.
+
+## 4. State model
+
+A normal state is a natural number. The body begins at normal state `1`.
+
+While reading a program, maintain the current normal state `c` and the set `V` of previously visited normal states. Initially:
+
+```text
+c = 1
+V = {1}
+```
+
+Every normal successor state must be absent from `V`; after it is accepted, add it to `V` and make it the new current state. A reference `(n)` is valid only when `n` is already in `V`. A reference is terminal and cannot be followed by another transition.
+
+## 5. Transition semantics
+
+The validator checks that each written operation is mathematically correct. It does not require the canonical or most efficient choice of operation.
+
+### 5.1 Expand
+
+An expand transition has the form:
+
+```text
+c>n
+```
+
+It is well-formed exactly when:
+
+```text
+n = c * B
+```
+
+`>` is permitted from every natural current state, including `c = T` and `c > T`. This deliberately permits non-canonical paths.
+
+If `n` is new, it is written as `n` and the program continues. If `n` is already visited, it is written as `(n)` and the program terminates:
+
+```text
+c>(n)
+```
+
+### 5.2 Split with a non-zero remainder
+
+A non-terminal split has one of these forms:
+
+```text
+c=p|r
+c=pxq|r
+```
+
+It is well-formed exactly when:
+
+```text
+c > T
+p = T
+q = c // T
+r = c % T
+c = p * q + r
+1 <= r < T
+```
+
+The `xq` portion is omitted if and only if `q = 1`. It is required when `q > 1`.
+
+The next state is `r`. If `r` is new, it is written as `r` and the program continues. If `r` is already visited, it is written as `(r)` and the program terminates:
+
+```text
+c=p|(r)
+c=pxq|(r)
+```
+
+Split is not allowed when `c <= T`. In particular, `c = T` must not be written as the meaningless expression `T = T * 1 + 0`.
+
+### 5.3 Exact split termination
+
+If a split has no remainder, it is an immediate successful termination:
+
+```text
+c=pxq|!
+```
+
+It is well-formed exactly when:
+
+```text
+c > T
+p = T
+q = c // T
+q >= 2
+c % T = 0
+c = p * q
+```
+
+The `|!` suffix represents that no remainder or retry state remains; it never creates state `0`. The `c` equally likely outcomes can be partitioned into `q` complete groups of `T` outcomes.
+
+For example:
+
+```text
+X6T3:1>6=3x2|!
+```
+
+## 6. Successful state termination
+
+The terminal marker `!` may immediately follow a normal state:
+
+```text
+c!
+```
+
+This form is well-formed exactly when `c = T`.
+
+It is not mandatory to terminate immediately when `c = T`: an expand transition may follow it to express a non-canonical path. However, a program that uses the standalone `!` marker must satisfy `c = T` at that point.
+
+## 7. Validation scope
+
+A validator must reject, at minimum:
+
+- malformed headers, tokens, or trailing text;
+- zero or negative state values;
+- bodies that do not start at `1`;
+- repeated normal states;
+- references to states not previously visited;
+- any text after a reference or terminal `!`;
+- incorrect expand or split arithmetic;
+- an omitted `xq` when `q > 1`, or a written `x1` when `q = 1`;
+- a non-exact split with `r = 0`;
+- a split from `c <= T`;
+- standalone `!` after a state other than `T`.
+
+Selecting the canonical path—expand when `c < T`, terminate when `c = T`, and split when `c > T`—is an optimization policy, not a well-formedness requirement. It must not be enforced by the general validator.