xbtm 0.1.0__py3-none-any.whl

xbtm/__init__.py

@@ -0,0 +1 @@
+from .main import Program, State, OperatorType, generate

xbtm/main.py

@@ -0,0 +1,219 @@
+from enum import Enum
+from dataclasses import dataclass
+from typing import Self
+import re
+import numpy as np
+from .validation import val_natural, val_parse, val_post_init
+
+def _uniquify(lst: list) -> tuple:
+    return tuple(dict.fromkeys(lst))
+
+class OperatorType(Enum):
+    EXPAND = '>'
+    SPLIT = '='
+    SPLIT_TO = '|'
+    SPLIT_MUL = 'x'
+    END = '!'
+
+    @property
+    def text(self):
+        return self.value
+
+@dataclass(frozen=True)
+class State:
+    number: int
+    is_ref: bool = False
+    is_node: bool = True
+
+    @property
+    def text(self) -> str:
+        if self.is_ref:
+            return f'({self.number})'
+        return str(self.number)
+
+    def __post_init__(self):
+        val_natural(self.number)
+        if not (isinstance(self.is_ref, bool)): raise TypeError(f"{self.is_ref} should be bool.")
+        if not (isinstance(self.is_node, bool)): raise TypeError(f"{self.is_node} should be bool.")
+
+@dataclass(frozen=True)
+class Program:
+    base: int
+    target: int
+    tokens: tuple[State|OperatorType, ...] = ()
+
+    @property
+    def text(self) -> str:
+        return f'X{self.base}T{self.target}:' + ''.join([token.text for token in self.tokens])
+    
+    @property
+    def nodes(self) -> tuple[int, ...]:
+        return _uniquify([
+            token.number
+            for token in self.tokens
+            if isinstance(token, State) and token.is_node
+        ])
+
+    def _state_at(self, i: int) -> State:
+        token = self.tokens[i]
+        assert isinstance(token, State), f"Type Mismatch, {token} should be State."
+        return token
+
+    def to_matrix(self) -> tuple[np.ndarray, np.ndarray]:
+        index = self.nodes
+        inv_index = {value: idx for idx, value in enumerate(index)}
+        node_count = len(index)
+
+        A = np.zeros((node_count, node_count))
+        b = np.zeros((node_count,))
+
+        for i, token in enumerate(self.tokens):
+            match token:
+                case OperatorType.EXPAND:
+                    A[inv_index[self._state_at(i-1).number], inv_index[self._state_at(i-1).number]] = 1
+                    A[inv_index[self._state_at(i-1).number], inv_index[self._state_at(i+1).number]] = -1
+                    b[inv_index[self._state_at(i-1).number]                                       ] = 1
+                
+                case OperatorType.SPLIT:
+                    A[inv_index[self._state_at(i-1).number], inv_index[self._state_at(i-1).number]] = 1
+                    
+                    if self.tokens[i+2] == OperatorType.SPLIT_MUL and self.tokens[i+5] != OperatorType.END:
+                        A[inv_index[self._state_at(i-1).number], inv_index[self._state_at(i+5).number]] = -self._state_at(i+5).number / self._state_at(i-1).number
+                    elif self.tokens[i+2] == OperatorType.SPLIT_TO:
+                        A[inv_index[self._state_at(i-1).number], inv_index[self._state_at(i+3).number]] = -self._state_at(i+3).number / self._state_at(i-1).number
+                
+                case OperatorType.END:
+                    if self.tokens[i-1] != OperatorType.SPLIT_TO:
+                        A[inv_index[self._state_at(i-1).number], inv_index[self._state_at(i-1).number]] = 1
+
+        return A,b
+
+    def get_trials(self) -> float:
+        return np.linalg.solve(*self.to_matrix())[0]
+
+    @classmethod
+    def parse(cls, dsl:str) -> Self:
+
+        val_parse(dsl)
+
+        header, body = dsl.split(':')
+        
+        base, target = map(
+            int,
+            re.fullmatch(r"X(\d+)T(\d+)", header).groups() # type: ignore
+        )
+
+        tokens = []
+        buffer = None
+        for ch in body:
+            match ch:
+                case '>':
+                    if buffer is not None: tokens.append(State(buffer))
+
+                    tokens.append(OperatorType.EXPAND)
+                
+                case '=':
+                    if buffer is not None: tokens.append(State(buffer))
+
+                    tokens.append(OperatorType.SPLIT)
+                
+                case 'x':
+                    if buffer is not None: tokens.append(State(buffer, is_node=False))
+
+                    tokens.append(OperatorType.SPLIT_MUL)
+                
+                case '|':
+                    if buffer is not None: tokens.append(State(buffer, is_node=False))
+
+                    tokens.append(OperatorType.SPLIT_TO)
+                
+                case '!':
+                    if buffer is not None: tokens.append(State(buffer))
+
+                    tokens.append(OperatorType.END)
+                    break;
+
+                case '(':
+                    pass
+                
+                case ')':
+                    if buffer is not None: tokens.append(State(buffer, is_ref=True))
+                    break;
+
+            if ch.isdigit():
+                buffer = (buffer or 0) * 10 + int(ch)
+
+            else:
+                buffer = None
+        
+        return cls(
+            base = base,
+            target = target,
+            tokens = tuple(tokens)
+        )
+
+    def __post_init__(self):
+        
+        val_post_init(
+            base=self.base,
+            target=self.target,
+            tokens=self.tokens
+        )
+
+def generate(base: int, target: int) -> Program:
+    val_natural(base)
+    val_natural(target)
+
+    if target>=2 and base==1: raise ValueError("When base({base}) is 1, target should be 1.")
+
+    current: int = 1
+    visited: set = {1}
+    tokens: list[State|OperatorType] = [State(1)]
+
+    while True:
+        if current < target:
+            current *= base
+
+            tokens.append(OperatorType.EXPAND)
+
+            if current in visited:
+                tokens.append(State(current, is_ref=True))
+                break
+
+            tokens.append(State(current))
+            visited.add(current)
+
+        elif current == target:
+            tokens.append(OperatorType.END)
+            break
+
+        else:
+            q:int = current // target
+            current %= target
+
+            tokens.append(OperatorType.SPLIT)
+            tokens.append(State(target, is_node=False))
+
+            if q != 1:
+                tokens.append(OperatorType.SPLIT_MUL)
+                tokens.append(State(q, is_node=False))
+
+            tokens.append(OperatorType.SPLIT_TO)
+
+            if current in visited:
+                tokens.append(State(current, is_ref=True))
+                break
+
+            elif current == 0:
+                tokens.append(OperatorType.END)
+                break
+
+            tokens.append(State(current))
+            visited.add(current)
+    
+    return Program(
+        base=base,
+        target=target,
+        tokens=tuple(tokens)
+    )
+

xbtm/validation.py

@@ -0,0 +1,277 @@
+# GENERATED USING CODEX
+# ...because manual labor for this was way beyond my limits.
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .main import OperatorType, State
+
+
+NAT = r"[1-9][0-9]*"
+REF = rf"\({NAT}\)"
+
+HEADER_RE = re.compile(rf"X{NAT}T{NAT}")
+
+EXPAND_RE = rf">{NAT}"
+SPLIT_RE = rf"={NAT}(?:x{NAT})?\|{NAT}"
+TERMINAL_RE = rf"(?:!|>{REF}|={NAT}(?:x{NAT})?\|{REF}|={NAT}x{NAT}\|!)"
+BODY_RE = re.compile(rf"{NAT}(?:{EXPAND_RE}|{SPLIT_RE})*{TERMINAL_RE}")
+
+
+def val_natural(num: int):
+    if not isinstance(num, int):
+        raise TypeError(f"{num} should be a natural number.")
+    if not num >= 1:
+        raise ValueError(f"{num} should be a natural number.")
+
+
+def val_parse(dsl: str):
+    if not isinstance(dsl, str):
+        raise TypeError(f"{dsl} should be a str.")
+
+    if dsl.count(":") != 1:
+        raise ValueError(f"{dsl} should contain exactly one ':'.")
+
+    header, body = dsl.split(":")
+
+    if HEADER_RE.fullmatch(header) is None:
+        raise ValueError(f"{header} is not a valid header.")
+
+    if BODY_RE.fullmatch(body) is None:
+        raise ValueError(f"{body} is not a valid body.")
+
+
+def val_post_init(base: int, target: int, tokens: tuple[State | OperatorType, ...]):
+    from .main import OperatorType, State
+
+    val_natural(base)
+    val_natural(target)
+
+    if target >= 2 and base == 1:
+        raise ValueError(f"When base({base}) is 1, target should be 1.")
+
+    if len(tokens) == 0:
+        raise ValueError("Program should have at least one token.")
+
+    first = tokens[0]
+    if not isinstance(first, State):
+        raise ValueError("Program should start with a state.")
+    if first.number != 1:
+        raise ValueError("Program should start at state 1.")
+    if first.is_ref:
+        raise ValueError("Program should not start with a reference.")
+    if not first.is_node:
+        raise ValueError("Program should start with a node.")
+
+    current = first.number
+    visited = {current}
+    i = 1
+
+    while i < len(tokens):
+        token = tokens[i]
+
+        if token == OperatorType.EXPAND:
+            i, current, terminated = _val_expand(
+                tokens=tokens,
+                i=i,
+                current=current,
+                visited=visited,
+                base=base,
+                State=State,
+            )
+            if terminated:
+                return
+            continue
+
+        if token == OperatorType.SPLIT:
+            i, current, terminated = _val_split(
+                tokens=tokens,
+                i=i,
+                current=current,
+                visited=visited,
+                target=target,
+                State=State,
+                OperatorType=OperatorType,
+            )
+            if terminated:
+                return
+            continue
+
+        if token == OperatorType.END:
+            if current != target:
+                raise ValueError("Standalone end should only appear at the target state.")
+            if i != len(tokens) - 1:
+                raise ValueError("No token should appear after end.")
+            return
+
+        raise ValueError(f"Unexpected token: {token}.")
+
+    raise ValueError("Program should end with end or reference.")
+
+
+def _val_expand(*, tokens, i, current, visited, base, State):
+    if i + 1 >= len(tokens):
+        raise ValueError("Expand should be followed by a state.")
+
+    next_state = tokens[i + 1]
+    if not isinstance(next_state, State):
+        raise ValueError("Expand should be followed by a state.")
+
+    expected = current * base
+    if next_state.number != expected:
+        raise ValueError(f"Expand should produce {expected}, not {next_state.number}.")
+
+    if next_state.is_ref:
+        if next_state.number not in visited:
+            raise ValueError(f"Reference state {next_state.number} has not been visited.")
+        if i + 2 != len(tokens):
+            raise ValueError("Reference should terminate the program.")
+        return len(tokens), current, True
+
+    if not next_state.is_node:
+        raise ValueError("Expand successor should be a node.")
+    if next_state.number in visited:
+        raise ValueError(f"State {next_state.number} should be written as a reference.")
+
+    visited.add(next_state.number)
+    return i + 2, next_state.number, False
+
+
+def _val_split(*, tokens, i, current, visited, target, State, OperatorType):
+    if current <= target:
+        raise ValueError("Split should only appear when current state is greater than target.")
+
+    if i + 2 >= len(tokens):
+        raise ValueError("Split expression is incomplete.")
+
+    split_target = tokens[i + 1]
+    if not isinstance(split_target, State):
+        raise ValueError("Split should be followed by a target term.")
+    if split_target.is_ref or split_target.is_node:
+        raise ValueError("Split target term should be a non-node state.")
+    if split_target.number != target:
+        raise ValueError(f"Split target should be {target}, not {split_target.number}.")
+
+    q = current // target
+    r = current % target
+
+    if tokens[i + 2] == OperatorType.SPLIT_MUL:
+        return _val_split_with_mul(
+            tokens=tokens,
+            i=i,
+            current=current,
+            visited=visited,
+            target=target,
+            q=q,
+            r=r,
+            State=State,
+            OperatorType=OperatorType,
+        )
+
+    if tokens[i + 2] == OperatorType.SPLIT_TO:
+        return _val_split_without_mul(
+            tokens=tokens,
+            i=i,
+            visited=visited,
+            q=q,
+            r=r,
+            State=State,
+            OperatorType=OperatorType,
+        )
+
+    raise ValueError("Split should contain '|' or 'x'.")
+
+
+def _val_split_with_mul(*, tokens, i, current, visited, target, q, r, State, OperatorType):
+    if i + 4 >= len(tokens):
+        raise ValueError("Split expression with multiplier is incomplete.")
+
+    multiplier = tokens[i + 3]
+    split_to = tokens[i + 4]
+
+    if not isinstance(multiplier, State):
+        raise ValueError("Split multiplier should be a state.")
+    if multiplier.is_ref or multiplier.is_node:
+        raise ValueError("Split multiplier should be a non-node state.")
+    if multiplier.number != q:
+        raise ValueError(f"Split multiplier should be {q}, not {multiplier.number}.")
+    if q == 1:
+        raise ValueError("Split multiplier should be omitted when q is 1.")
+    if split_to != OperatorType.SPLIT_TO:
+        raise ValueError("Split multiplier should be followed by '|'.")
+
+    if i + 5 >= len(tokens):
+        raise ValueError("Split remainder is missing.")
+
+    successor = tokens[i + 5]
+
+    if successor == OperatorType.END:
+        if r != 0:
+            raise ValueError("Exact split termination requires zero remainder.")
+        if q < 2:
+            raise ValueError("Exact split termination requires q >= 2.")
+        if current != target * q:
+            raise ValueError("Exact split arithmetic is invalid.")
+        if i + 6 != len(tokens):
+            raise ValueError("No token should appear after exact split termination.")
+        return len(tokens), current, True
+
+    return _val_split_remainder(
+        tokens=tokens,
+        i=i,
+        successor_i=i + 5,
+        successor=successor,
+        visited=visited,
+        r=r,
+        State=State,
+    )
+
+
+def _val_split_without_mul(*, tokens, i, visited, q, r, State, OperatorType):
+    if q != 1:
+        raise ValueError("Split multiplier should be written when q is greater than 1.")
+
+    if i + 3 >= len(tokens):
+        raise ValueError("Split remainder is missing.")
+
+    successor = tokens[i + 3]
+    if successor == OperatorType.END:
+        raise ValueError("Exact split termination should include an explicit multiplier.")
+
+    return _val_split_remainder(
+        tokens=tokens,
+        i=i,
+        successor_i=i + 3,
+        successor=successor,
+        visited=visited,
+        r=r,
+        State=State,
+    )
+
+
+def _val_split_remainder(*, tokens, i, successor_i, successor, visited, r, State):
+    if r == 0:
+        raise ValueError("Zero remainder should be written as exact split termination.")
+
+    if not isinstance(successor, State):
+        raise ValueError("Split remainder should be a state.")
+    if successor.number != r:
+        raise ValueError(f"Split remainder should be {r}, not {successor.number}.")
+
+    if successor.is_ref:
+        if successor.number not in visited:
+            raise ValueError(f"Reference state {successor.number} has not been visited.")
+        if successor_i + 1 != len(tokens):
+            raise ValueError("Reference should terminate the program.")
+        return len(tokens), successor.number, True
+
+    if not successor.is_node:
+        raise ValueError("Split remainder should be a node.")
+    if successor.number in visited:
+        raise ValueError(f"State {successor.number} should be written as a reference.")
+
+    visited.add(successor.number)
+    return successor_i + 1, successor.number, False

xbtm-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+xbtm/__init__.py,sha256=gsc-c20HzxEpTxL1FwEAY13xuFGJvmtwLqxUxdqiFxg,56
+xbtm/main.py,sha256=_eWjcgRC-c2-yKZ5S3xqU-HdRG6pcLuXy5UhvByrpkM,6847
+xbtm/validation.py,sha256=Nt2friYDdFbL_UZLLRRmze4ARuWU7GX-R6rAPMtFzKA,8946
+xbtm-0.1.0.dist-info/METADATA,sha256=p_I6VDooal9SSGPdhFLKDpgiyYFXduBJNRvBs2DvnpM,3384
+xbtm-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+xbtm-0.1.0.dist-info/licenses/LICENSE,sha256=hmxe-_8PyFXkmhDqeol7jo9z566NxqgxP5nUfpCZbWk,1094
+xbtm-0.1.0.dist-info/RECORD,,

xbtm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

xbtm-0.1.0.dist-info/licenses/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.