umbi 0.0.1__tar.gz

umbi-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roman Andriushchenko
+
+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.

umbi-0.0.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: umbi
+Version: 0.0.1
+Summary: Library for binary encoding of annotated transition systems
+Author-email: Roman Andriushchenko <roman.andriu@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Roman Andriushchenko
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/randriu/umbi
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: marshmallow
+Requires-Dist: python-magic
+Requires-Dist: tomli
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: toml-sort; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: bumpver; extra == "dev"
+Dynamic: license-file
+
+# umbi
+
+## Installation:
+
+(optional) create and activate a python environment:
+
+```
+$ python -m venv venv
+$ source venv/bin/activate
+```
+
+Install `umbi` via
+```
+(venv) $ pip install umbi
+```
+
+## Running umbi
+
+Examples:
+```
+(venv) $ umbi --import-umb /path/to/input.umb
+(venv) $ umbi --import-umb /path/to/input.umb --export-umb /path/to/output.umb
+(venv) $ umbi --import-umb /path/to/input.umb --export-umb /path/to/output.umb --log-level=DEBUG
+```

umbi-0.0.1/README.md

@@ -0,0 +1,24 @@
+# umbi
+
+## Installation:
+
+(optional) create and activate a python environment:
+
+```
+$ python -m venv venv
+$ source venv/bin/activate
+```
+
+Install `umbi` via
+```
+(venv) $ pip install umbi
+```
+
+## Running umbi
+
+Examples:
+```
+(venv) $ umbi --import-umb /path/to/input.umb
+(venv) $ umbi --import-umb /path/to/input.umb --export-umb /path/to/output.umb
+(venv) $ umbi --import-umb /path/to/input.umb --export-umb /path/to/output.umb --log-level=DEBUG
+```

umbi-0.0.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "umbi"
+version = "0.0.1"
+description = "Library for binary encoding of annotated transition systems"
+readme = "README.md"
+authors = [{name = "Roman Andriushchenko", email = "roman.andriu@gmail.com"}]
+license = {file = "LICENSE"}
+dependencies = [
+  "marshmallow",
+  "python-magic",
+  "tomli"
+]
+requires-python = ">=3.9"
+
+[project.urls]
+Homepage = "https://github.com/randriu/umbi"
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pip-tools",
+  "black",
+  "isort",
+  "toml-sort",
+  "twine",
+  "bumpver"
+]
+
+[tool.setuptools]
+packages = ["umbi"]
+include-package-data = true
+
+[project.scripts]
+umbi = "umbi.__main__:main"
+
+[tool.bumpver]
+current_version = "0.0.1"
+version_pattern = "MAJOR.MINOR.PATCH"
+commit_message = "bump version {old_version} -> {new_version}"
+tag_message = "{new_version}"
+tag_scope = "default"
+pre_commit_hook = ""
+post_commit_hook = ""
+commit = false
+tag = false
+push = false
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = ['current_version = "{version}"', 'version = "{version}"']

umbi-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

umbi-0.0.1/umbi/__init__.py

@@ -0,0 +1,33 @@
+import logging
+import os
+
+import tomli
+
+logging.basicConfig(level=logging.DEBUG, format="%(levelname)s - %(message)s")
+
+from .explicit_ats import ExplicitAts
+from .io_bytes import *
+from .io_json import *
+from .io_tar import *
+from .io_umb import *
+
+# from .simple_ats import SimpleAts
+
+
+def get_pyproject_attribute(attribute, default):
+    """Read an attribute from pyproject.toml."""
+    pyproject_path = os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
+    try:
+        with open(pyproject_path, "rb") as f:
+            project_data = tomli.load(f)["project"]
+            return project_data.get(attribute)
+    except (FileNotFoundError, KeyError):
+        return default
+
+
+__toolname__ = get_pyproject_attribute("name", "unknown")
+__version__ = get_pyproject_attribute("version", "0.0.0")
+
+# TODO move to config file
+__format_version__ = 0
+__format_revision__ = 1

umbi-0.0.1/umbi/__main__.py

@@ -0,0 +1,35 @@
+import logging
+
+import click
+
+import umbi
+
+
+@click.command()
+@click.option(
+    "--log-level",
+    type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]),
+    default="INFO",
+    show_default=True,
+    required=False,
+    help="logging level",
+)
+@click.option("--import-umb", type=click.Path(), required=False, help=".umb filepath to import")
+@click.option("--export-umb", type=click.Path(), required=False, help=".umb filepath to export")
+def main(log_level, import_umb, export_umb):
+
+    logging.getLogger().setLevel(level=getattr(logging, log_level))
+    logging.debug(f"this is {umbi.__toolname__} v.{umbi.__version__}")
+
+    ats = None
+    if import_umb is not None:
+        logging.info(f"loading ${import_umb}")
+        ats = umbi.read_umb(import_umb)
+    if export_umb is not None:
+        if ats is None:
+            raise ValueError("--export-umb specified, but nothing to export")
+        umbi.write_umb(ats, export_umb)
+
+
+if __name__ == "__main__":
+    main()

umbi-0.0.1/umbi/ats.py

@@ -0,0 +1,136 @@
+import collections
+import random
+
+import umbi
+
+
+class SimpleAts:
+    """Annotated transition system."""
+
+    def __init__(self):
+        self.info = umbi.AtsInfoSchema.empty_object()
+
+        self.time = None
+        self.branch_probability_type = None
+
+        self.num_players = 1
+        self.num_actions = 1
+
+        self.initial_states = None
+        self.state_choices = []
+        self.choice_branches = []
+        self.branch_target = []
+        self.branch_value = []
+        self.annotations = {}
+
+    def validate_field_set(self, field: str):
+        field_value = getattr(self, field)
+        if field_value is None:
+            raise ValueError(f"SimpleAts: field '{field}' is not set")
+
+    def validate_field_in(self, field: str, domain: list):
+        """Validate that the field has the value within the given domain."""
+        self.validate_field_set(field)
+        field_value = getattr(self, field)
+        if field_value not in domain:
+            raise ValueError(f"SimpleAts: field '{field}' must be in {domain}")
+
+    @staticmethod
+    def validate_is_list(l, name, length=None):
+        if not isinstance(l, list):
+            raise ValueError(f"SimpleAts: '{name}' must be a list")
+        if length is not None and not len(l) == length:
+            raise ValueError(f"SimpleAts: '{name}' must be of length {length}")
+
+    @property
+    def num_states(self):
+        return len(self.state_choices)
+
+    @property
+    def num_initial_states(self):
+        return len(self.initial_states)
+
+    @property
+    def num_choices(self):
+        return len(self.choice_branches)
+
+    @property
+    def num_branches(self):
+        return len(self.branch_target)
+
+    def validate(self):
+        self.validate_field_in("time", ["discrete", "stochastic", "urgent-stochastic"])
+        self.validate_field_in("branch_values", ["none", "number", "interval"])
+        if self.branch_values != "none":
+            self.validate_field_in("branch_value_type", ["double", "rational"])
+
+        self.validate_field_set("num_states")
+        self.validate_field_set("num_initial_states")
+        self.validate_field_set("num_choices")
+        self.validate_field_set("num_branches")
+        self.validate_field_set("num_players")
+        self.validate_field_set("num_actions")
+
+        SimpleAts.validate_is_list(self.initial_states, "initial_states")
+        if not all([state < self.num_states for state in self.initial_states]):
+            raise ValueError(f"SimpleAts: invalid initial states")
+
+        SimpleAts.validate_is_list(self.choice_branches, "choice_branches", self.num_choices)
+        for choice, branches in enumerate(self.choice_branches):
+            SimpleAts.validate_is_list(branches, f"choice_branches[{choice}]")
+            if not len(branches) > 0:
+                raise ValueError(f"SimpleAts: 'choice_branches[{choice}]' must be a non-empty list")
+
+        SimpleAts.validate_is_list(self.branch_target, "branch_target")
+        SimpleAts.validate_is_list(self.branch_value, "branch_target")
+
+    # def add_state(self):
+    #     self.state_choices.append([])
+
+    # def add_states(self, num_new_states : int):
+    #     for _ in range(num_new_states):
+    #         self.add_state()
+
+    def add_annotation(self, key: str):
+        if key in self.annotations:
+            print(f"warning: redefining annotation {key}")
+        annotation = umbi.AnnotationSchema.empty_object()
+        self.annotations[key] = annotation
+        return annotation
+
+    def choice_successors(self, choice: int) -> set:
+        successors = set()
+        for branch in self.choice_branches[choice]:
+            successors.add(self.branch_target[branch])
+        return successors
+
+    def state_successors(self, state: int) -> set:
+        successors = set()
+        for choice in self.state_choices[state]:
+            successors.update(self.choice_successors(choice))
+        return successors
+
+    def choice_distribution(self, choice: int) -> dict:
+        distr = collections.defaultdict(int)
+        for branch in self.choice_branches[choice]:
+            target, value = self.branches[branch]
+            distr[target] += value
+        return dict(distr)
+
+    def sample_choice(self, state: int) -> int:
+        return random.choice(self.state_choices[state])
+
+    def sample_choice_target(self, choice: int) -> int:
+        distr = self.choice_distribution(choice)
+        target = random.choices(population=list(distr.keys()), weights=list(distr.values()), k=1)[0]
+        return target
+
+    def sample_path(self, state=None, length=0):
+        if state is None:
+            state = random.choice(self.initial_states)
+        path = [state]
+        for _ in range(length):
+            choice = self.sample_choice(state)
+            state = self.sample_choice_target(choice)
+            path.append(state)
+        return path

umbi-0.0.1/umbi/explicit_ats.py

@@ -0,0 +1,23 @@
+# import umbi
+
+
+class ExplicitAts:
+    """Annotated transition system in an explicit format matching the .umb file format."""
+
+    def __init__(self):
+        self.info = None
+
+        self.initial_states = None
+        self.state_choices = None
+        self.state_to_player = None
+        self.exit_rates = None
+
+        self.choice_branches = None
+        self.branch_target = None
+        self.branch_probabilities = None
+
+        self.choice_to_action = None
+        self.branch_to_action = None
+        self.action_to_string = None
+
+        self.annotations = {}

umbi-0.0.1/umbi/io_bytes.py

@@ -0,0 +1,113 @@
+import logging
+import struct
+
+import umbi
+
+
+def bytes_to_string(data: bytes) -> str:
+    """Convert a binary string to a utf-8 string."""
+    return data.decode("utf-8")
+
+
+def string_to_bytes(string: str) -> bytes:
+    """Convert a utf-8 string to a binary string."""
+    return string.encode("utf-8")
+
+
+def assert_key_in_dict(table: dict, key, desc: str):
+    if key not in table:
+        raise ValueError(f"{desc} must be in {table} but is {key}")
+
+
+def value_type_to_struct_format(value_type: str) -> str:
+    """Convert a value type to a formatting string for struct."""
+    table = {
+        "int32": "i",
+        "uint32": "I",
+        "int64": "q",
+        "uint64": "Q",
+        "double": "d",
+    }
+    assert_key_in_dict(table, value_type, "value type")
+    return table[value_type]
+
+
+def value_type_to_size(value_type: str) -> int:
+    """Map value type to its size."""
+    table = {
+        "int32": 4,
+        "uint32": 4,
+        "int64": 8,
+        "uint64": 8,
+        "double": 8,
+    }
+    assert_key_in_dict(table, value_type, "value type")
+    return table[value_type]
+
+
+def endianness_to_struct_format(little_endian: bool) -> str:
+    """
+    Convert endianness flag to a formatting string for struct.
+    :param little_endian: True for little-endian, False for big-endian
+    """
+    table = {False: ">", True: "<"}
+    assert_key_in_dict(table, little_endian, "endianness")
+    return table[little_endian]
+
+
+def vector_to_bytes(vector: list, value_type: str, little_endian: bool = True) -> bytes:
+    """Encode a list of values as a binary string.
+
+    :param value_type: vector element type, one of {"bool", "uint64", "double"}
+    """
+    if len(vector) == 0:
+        logging.warning("exporting empty binary file")
+        return b""
+
+    if value_type == "char":
+        return string_to_bytes(vector)
+
+    if value_type == "bool":
+        # TODO respect endianness
+        assert little_endian, "big-endianness for bitvectors is not implemented"
+        # drop trailing zeros?
+
+        # pad vector up to 64 bits
+        target_pad = 64
+        num_pad = (target_pad - (len(vector) % target_pad)) % target_pad
+        vector = vector + [False] * num_pad
+        bitmask = b""
+        for byte_index in range(len(vector) // 8):
+            bits = vector[byte_index * 8 : byte_index * 8 + 8]
+            byte_int = sum((1 << i) for i, bit in enumerate(bits) if bit)
+            bitmask += byte_int.to_bytes(1, byteorder="little")
+        return bitmask
+
+    for item in vector:
+        assert isinstance(item, int) or isinstance(item, float)
+        if value_type in ["uint32", "uint64"]:
+            assert isinstance(item, int) and item >= 0
+    endian_format = endianness_to_struct_format(little_endian)
+    type_format = value_type_to_struct_format(value_type)
+    return struct.pack(f"{endian_format}{len(vector)}{type_format}", *vector)
+
+
+def bytes_to_vector(vector_bytes: bytes, value_type: str, little_endian: bool = True) -> list:
+    """
+    Decode a binary string as a list of numbers.
+
+    :param value_type: vector element type, one of {"bool", "uint64", "double"}
+    """
+    if value_type == "char":
+        return bytes_to_string(vector_bytes)
+    if value_type == "bool":
+        bitvector = []
+        for bitmask in vector_bytes:
+            for i in range(8):
+                bitvector.append((bitmask >> i) & 1 == 1)
+        return bitvector
+    type_format = value_type_to_struct_format(value_type)
+    endian_format = endianness_to_struct_format(little_endian)
+    num_entries = len(vector_bytes) // value_type_to_size(value_type)
+    vector = struct.unpack(f"{endian_format}{num_entries}{type_format}", vector_bytes)
+    return list(vector)

umbi-0.0.1/umbi/io_json.py

@@ -0,0 +1,43 @@
+import json
+import logging
+import typing
+
+import umbi
+
+""" A type alias for (high-level) json objects. """
+jsonlike = typing.Union[dict, list]
+
+
+def json_remove_none(json_obj: object):
+    """Recursively remove all None (null) values from a json (sub-)object."""
+    if isinstance(json_obj, dict):
+        return {k: json_remove_none(v) for k, v in json_obj.items() if v is not None}
+    elif isinstance(json_obj, list):
+        return [json_remove_none(v) for v in json_obj]
+    else:
+        return json_obj
+
+
+def json_to_string(json_obj: jsonlike, remove_none: bool = False, indent: int = 4) -> str:
+    """Encode a json object as a string."""
+    if remove_none:
+        json_obj = json_remove_none(json_obj)
+    return json.dumps(json_obj, indent=indent)
+
+
+def string_to_json(json_str: str) -> jsonlike:
+    """Convert a string to a json object."""
+    return json.loads(json_str)
+
+
+def json_show(json_obj: jsonlike):
+    """Print a json object to stdout."""
+    logging.debug(json_to_string(json_obj))
+
+
+def bytes_to_json(data: bytes) -> jsonlike:
+    return string_to_json(umbi.bytes_to_string(data))
+
+
+def json_to_bytes(json_obj: jsonlike) -> bytes:
+    return umbi.string_to_bytes(json_to_string(json_obj))

umbi-0.0.1/umbi/io_tar.py

@@ -0,0 +1,160 @@
+import io
+import logging
+import tarfile
+
+import umbi
+
+
+def tar_filenames(tarpath: str) -> list[str]:
+    """Retrieve filenames in the tarball file."""
+    with tarfile.open(tarpath, mode="r:*") as tar:
+        return [m.name for m in tar.getmembers() if m.isfile()]
+
+
+def tar_read_file(tarpath: str, filename: str) -> object:
+    """Read contents of a specific file in the tarball."""
+    with tarfile.open(tarpath, mode="r:*") as tar:
+        filenames = [m.name for m in tar.getmembers() if m.isfile()]
+        if filename not in filenames:
+            raise KeyError(f"{tarpath} has no file {filename}")
+        member = tar.getmember(filename)
+        return tar.extractfile(member).read()
+
+
+def tar_read(tarpath: str) -> dict[str, bytes]:
+    """
+    Read all contents of a tarball file.
+
+    :returns: a dictionary filename -> contents
+    """
+    filename_data = {}
+    with tarfile.open(tarpath, mode="r:*") as tar:
+        for member in tar.getmembers():
+            if member.isfile():
+                filename_data[member.name] = tar.extractfile(member).read()
+    return filename_data
+
+
+def tar_write(tarpath: str, filename_data: dict[str, bytes], gzip: bool = True):
+    """
+    Create a tarball file with the given contents.
+
+    :param tarpath: path to a tarball file
+    :param filename_data: a dictionary filename -> binary string
+    :param gzip: if True, the tarball file will be gzipped
+    """
+    mode = "w"
+    if gzip:
+        mode = "w:gz"
+    tar_stream = io.BytesIO()
+    with tarfile.open(fileobj=tar_stream, mode=mode) as tar:
+        for filename, data in filename_data.items():
+            tar_info = tarfile.TarInfo(name=filename)
+            tar_info.size = len(data)
+            tar.addfile(tar_info, io.BytesIO(data))
+    tar_bytes = tar_stream.getvalue()
+    with open(tarpath, "wb") as file:
+        file.write(tar_bytes)
+    logging.info(f"data exported to {tarpath}")
+
+
+def row_start_to_ranges(row_start: list) -> list:
+    """Convert row start indices to ranges."""
+    ranges = []
+    num_rows = len(row_start) - 1
+    for row in range(num_rows):
+        ranges.append(list(range(row_start[row], row_start[row + 1])))
+    return ranges
+
+
+def ranges_to_row_start(ranges: list) -> list:
+    """Convert ranges to row start indices."""
+    row_start = [interval[0] for interval in ranges]
+    row_start.append(ranges[-1][-1] + 1)
+    assert len(row_start) == len(ranges) + 1
+    return row_start
+
+
+def indices_to_bitvector(vector: list[int], num_entries: int) -> list[bool]:
+    """Convert a list of unsigned integers to a bitvector.
+
+    :param vector: a list of unsigned integers
+    :param num_entries: the size of the resulting bitvector, must be no smaller than max(vector)
+    """
+    assert max(vector) < num_entries
+    bitvector = [False] * num_entries
+    for x in vector:
+        bitvector[x] = True
+    return bitvector
+
+
+def bitvector_to_indices(bitvector: list[bool]) -> list[int]:
+    """Convert a bitvector to a list of indices set to True.
+
+    :param bitvector: a list of bools
+    """
+    return [i for i, bit in enumerate(bitvector) if bit]
+
+
+class TarReader:
+    """An auxiliary class to simplify tar reading and to keep track of (un)used files."""
+
+    def __init__(self, tarpath: str):
+        self.tarpath = tarpath
+        self.filenames = tar_filenames(tarpath)
+        self.files_read = set()
+
+        filenames_str = "\n".join(self.filenames)
+        logging.debug(f"found the following files:\n{filenames_str}")
+
+    def warn_unread_files(self):
+        """Print warning about unread files from the tarfile, if such exist."""
+        unread_files = [f for f in self.filenames if f not in self.files_read]
+        if len(unread_files) > 0:
+            unread_files_str = "\n".join(unread_files)
+            logging.warning(
+                f'the following files from "{self.tarpath}" were not used during parsing:\n{unread_files_str}'
+            )
+
+    def read(self, filename: str, file_format: str, csr: bool = False) -> object:
+        """Read contents and process a specific file in the tarball.
+
+        :param file_format: one of ["json", "bool", "uint32","uint64", "double"]
+        """
+        if filename not in self.filenames:
+            raise KeyError(f"tar archive {self.tarpath} has no required file {filename}")
+        self.files_read.add(filename)
+        data = tar_read_file(self.tarpath, filename)
+
+        if file_format == "json":
+            return umbi.bytes_to_json(data)
+
+        data = umbi.bytes_to_vector(data, file_format)
+        if file_format == "bool":
+            data = bitvector_to_indices(data)
+        if csr:
+            data = row_start_to_ranges(data)
+        return data
+
+
+class TarWriter:
+    """An auxiliary class to simplify tar writing."""
+
+    def __init__(self):
+        self.filename_data = dict[str, bytes]()
+
+    def add(self, data: object, filename: str, file_format: str, csr: bool = False):
+        if csr:
+            data = ranges_to_row_start(data)
+
+        if file_format == "json":
+            data = umbi.json_to_bytes(data)
+        else:
+            # if file_format == "bool":
+            #     data = indices_to_bitvector(data)
+            data = umbi.vector_to_bytes(data, file_format)
+
+        self.filename_data[filename] = data
+
+    def write(self, tarpath: str):
+        umbi.tar_write(tarpath, self.filename_data)

umbi-0.0.1/umbi/io_umb.py

@@ -0,0 +1,364 @@
+import logging
+import time
+from types import SimpleNamespace
+
+from marshmallow import (
+    Schema,
+    ValidationError,
+    fields,
+    post_load,
+    validate,
+    validates_schema,
+)
+
+import umbi
+
+
+class FieldUint(fields.Int):
+    """Custom marshmallow field for unsigned integers."""
+
+    def _deserialize(self, value, attr, data, **kwargs):
+        result = super()._deserialize(value, attr, data, **kwargs)
+        if result < 0:
+            raise ValidationError(f"value {value} must be an unsigned integer")
+        return result
+
+
+class JsonSchema(Schema):
+    """An abstract class to represent specific schemas that will follow."""
+
+    @post_load
+    def make_object(self, data, **kwargs):
+        """Create an object with attributes matching the json fields."""
+        for field in self.fields:
+            if field not in data:
+                data[field] = None
+        return SimpleNamespace(**data)
+
+    @classmethod
+    def empty_object(cls):
+        """Create an empty object with attributes (set to None) corresponding to the fields of schema."""
+        return SimpleNamespace(**{field: None for field in cls().fields})
+
+    @validates_schema
+    def validate_fields(self, data, **kwargs):
+        """A method that is called upon the creation of the object to validate the fields."""
+        pass
+
+    @classmethod
+    def from_json(cls, json_obj) -> SimpleNamespace:
+        """Parse from a json object.
+        :returns None if any exception occurs"""
+        try:
+            return cls().load(json_obj)
+        except ValidationError as err:
+            logging.error(f"{cls} validation error:")
+            logging.error(umbi.json_to_string(err.messages))
+            raise err
+
+
+class ModelDataSchema(JsonSchema):
+    """Model data schema."""
+
+    name = fields.String(data_key="name")
+    version = fields.String(data_key="version")
+    authors = fields.List(fields.String(), data_key="authors")
+    description = fields.String(data_key="description")
+    comment = fields.String(data_key="comment")
+    doi = fields.String(data_key="doi")
+    url = fields.String(data_key="url")
+
+
+class FileDataSchema(JsonSchema):
+    """File data schema."""
+
+    tool = fields.String(data_key="tool")
+    tool_version = fields.String(data_key="tool-version")
+    creation_date = FieldUint(data_key="creation-date")
+    parameters = fields.Raw(data_key="parameters")
+
+    @classmethod
+    def this_tool_object(cls):
+        """Create an object with attributes set according to this tool."""
+        obj = SimpleNamespace(**{field: None for field in cls().fields})
+        obj.tool = umbi.__toolname__
+        obj.tool_version = umbi.__version__
+        obj.creation_date = int(time.time())
+        return obj
+
+
+class TransitionSystemSchema(JsonSchema):
+    """ATS index file schema."""
+
+    time = fields.String(
+        data_key="time", required=True, validate=validate.OneOf(["discrete", "stochastic", "urgent-stochastic"])
+    )
+
+    num_players = FieldUint(data_key="#players", required=True)
+    num_states = FieldUint(data_key="#states", required=True)
+    num_initial_states = FieldUint(data_key="#initial-states", required=True)
+    num_choices = FieldUint(data_key="#choices", required=True)
+    num_actions = FieldUint(data_key="#actions", required=True)
+    num_branches = FieldUint(data_key="#branches", required=True)
+
+    branch_probability_type = fields.String(
+        data_key="branch-probability-type",
+        required=True,
+        validate=validate.OneOf(["none", "double", "rational", "double-interval", "rational-interval"]),
+    )
+
+
+class AtomicPropositionSchema(JsonSchema):
+    """Atomic proposition schema."""
+
+    alias = fields.String(data_key="alias", required=False)
+    description = fields.String(data_key="description", required=False)
+    applies_to = fields.List(
+        fields.String(validate=validate.OneOf(["states", "choices", "branches"])), data_key="applies-to", required=True
+    )
+    type = fields.String(
+        data_key="type", required=False, validate=validate.OneOf(["bool"]), load_default="bool"
+    )  # TODO discuss
+
+
+class RewardSchema(JsonSchema):
+    """Reward model schema."""
+
+    alias = fields.String(data_key="alias")
+    description = fields.String(data_key="description")
+    applies_to = fields.List(
+        fields.String(validate=validate.OneOf(["states", "choices", "branches"])),
+        data_key="applies-to",
+        required=True,
+    )
+    type = fields.String(
+        data_key="type",
+        required=True,
+        validate=validate.OneOf(["double", "rational", "double-interval", "rational-interval"]),
+    )
+    lower = fields.Float(data_key="lower", required=False)
+    upper = fields.Float(data_key="upper", required=False)
+
+
+class VariableValuationSchema(JsonSchema):
+    """Variable valuation schema."""
+
+    alias = fields.String(data_key="alias", required=False)
+    description = fields.String(data_key="description", required=False)
+    applies_to = fields.List(
+        fields.String(validate=validate.OneOf(["states", "choices", "branches"])), data_key="applies-to", required=True
+    )
+    type = fields.String(
+        data_key="type", required=True, validate=validate.OneOf(["bool", "int", "int32", "uint32", "int64", "uint64"])
+    )
+
+    @post_load
+    def make_object(self, data, **kwargs):
+        obj = super().make_object(data, **kwargs)
+        if obj.type == "int":  # TODO discuss
+            logging.warning("variable annotation type is int, interpreting as int32")
+            obj.type = "int32"
+        return obj
+
+
+class AnnotationSchema(JsonSchema):
+    """Single annotation schema."""
+
+    aps = fields.Dict(
+        keys=fields.String(), values=fields.Nested(AtomicPropositionSchema), data_key="aps", required=False
+    )
+    rewards = fields.Dict(keys=fields.String(), values=fields.Nested(RewardSchema), data_key="rewards", required=False)
+    variables = fields.Dict(
+        keys=fields.String(), values=fields.Nested(VariableValuationSchema), data_key="variables", required=False
+    )
+
+
+class AtsInfoSchema(JsonSchema):
+    """ATS index file schema."""
+
+    format_version = FieldUint(data_key="format-version", required=True)
+    format_revision = FieldUint(data_key="format-revision", required=True)
+    model_data = fields.Nested(ModelDataSchema, data_key="model-data", required=False)
+    file_data = fields.Nested(FileDataSchema, data_key="file-data", required=False)
+    transition_system = fields.Nested(TransitionSystemSchema, data_key="transition-system", required=True)
+    annotations = fields.Nested(AnnotationSchema, data_key="annotations", required=False)
+
+    @classmethod
+    def empty_object(cls):
+        """Create an empty object with attributes (set to None) corresponding to the fields of schema."""
+        obj = SimpleNamespace(**{field: None for field in cls().fields})
+        obj.format_version = umbi.__format_version__
+        obj.format_revision = umbi.__format_revision__
+        obj.model_data = ModelDataSchema.empty_object()
+        obj.file_data = FileDataSchema.empty_object()
+        obj.transition_system = TransitionSystemSchema.empty_object()
+        obj.annotations = AnnotationSchema.empty_object()
+        return obj
+
+
+def read_index_file(reader: umbi.TarReader, ats: umbi.ExplicitAts):
+    json_obj = reader.read("index.json", "json")
+    umbi.json_show(json_obj)
+    ats.info = AtsInfoSchema.from_json(json_obj)
+
+
+def write_index_file(writer: umbi.TarWriter, ats: umbi.ExplicitAts):
+    info = AtsInfoSchema().empty_object()
+    info.model_data = ats.info.model_data
+    info.file_data = FileDataSchema.this_tool_object()
+    info.transition_system = ats.info.transition_system
+    info.annotations = ats.info.annotations
+    # FIXME variable type int32->int
+    if info.annotations.variables is not None:
+        for key, annotation in info.annotations.variables.items():
+            if annotation.type == "int32":
+                logging.warning("variable annotation type is int32, storing as int in the index file")
+                annotation.type = "int"
+    json_obj = AtsInfoSchema().dump(info)
+    json_obj = umbi.json_remove_none(json_obj)
+    umbi.json_show(json_obj)
+    writer.add(json_obj, "index.json", "json")
+
+
+def read_state_files(reader: umbi.TarReader, ats: umbi.ExplicitAts):
+    ts = ats.info.transition_system
+    ats.initial_states = reader.read("initial-states.bin", "bool")
+    if ts.num_players > 0:
+        ats.state_choices = reader.read("state-to-choice.bin", "uint64", csr=True)
+    if ts.num_players > 1:
+        ats.state_to_player = reader.read("state-to-player.bin", "uint64")
+    if ts.time in ["stochastic", "urgent-stochastic"]:
+        ats.exit_rates = reader.read("exit-rates.bin", "double")  # TODO discuss
+
+
+def write_state_files(writer: umbi.TarWriter, ats: umbi.ExplicitAts):
+    ts = ats.info.transition_system
+    writer.add(umbi.indices_to_bitvector(ats.initial_states, ts.num_states), "initial-states.bin", "bool")
+    if ts.num_players > 0:
+        writer.add(umbi.ranges_to_row_start(ats.state_choices), "state-to-choice.bin", "uint64")
+    if ts.num_players > 1:
+        writer.add(ats.state_to_player, "state-to-player.bin", "uint64")
+    if ts.time in ["stochastic", "urgent-stochastic"]:
+        writer.add(ats.exit_rates, "exit-rates.bin", "double")  # TODO discuss
+
+
+def read_branch_files(reader: umbi.TarReader, ats: umbi.ExplicitAts):
+    ts = ats.info.transition_system
+    if ts.num_branches > ts.num_choices:
+        ats.choice_branches = reader.read("choice-to-branch.bin", "uint64", csr=True)
+    ats.branch_target = reader.read("branch-to-target.bin", "uint64")
+    assert ts.branch_probability_type == "double", "not implemented yet"
+    ats.branch_probabilities = reader.read("branch-probabilities.bin", "double")
+
+
+def write_branch_files(writer: umbi.TarWriter, ats: umbi.ExplicitAts):
+    ts = ats.info.transition_system
+    if ts.num_branches > ts.num_choices:
+        writer.add(ats.choice_branches, "choice-to-branch.bin", "uint64", csr=True)
+    writer.add(ats.branch_target, "branch-to-target.bin", "uint64")
+    assert ts.branch_probability_type == "double", "not implemented yet"
+    writer.add(ats.branch_probabilities, "branch-probabilities.bin", "double")
+
+
+def read_action_files(reader: umbi.TarReader, ats: umbi.ExplicitAts):
+    ts = ats.info.transition_system
+    if ts.time == "discrete":
+        if ts.num_players > 0:
+            ats.choice_to_action = reader.read("choice-to-action.bin", "uint32")
+    else:
+        ats.branch_to_action = reader.read("branch-to-action.bin", "uint32")
+    if "action-to-action-strings.bin" in reader.filenames and "action-strings.bin" in reader.filenames:
+        action_string_offset = reader.read("action-to-action-strings.bin", "uint32")
+        action_string_chars = reader.read("action-strings.bin", "char")
+        ats.action_to_string = []
+        for action in range(ts.num_actions):
+            action_string = action_string_chars[action_string_offset[action] : action_string_offset[action + 1]]
+            ats.action_to_string.append(action_string)
+
+
+def write_action_files(writer: umbi.TarWriter, ats: umbi.ExplicitAts):
+    ts = ats.info.transition_system
+    if ts.time == "discrete":
+        if ts.num_players > 0:
+            writer.add(ats.choice_to_action, "choice-to-action.bin", "uint32")
+    else:
+        writer.add(ats.branch_to_action, "branch-to-action.bin", "uint32")
+    if ats.action_to_string is not None:
+        action_string_offset = [0]
+        action_string_chars = ""
+        for action, string in enumerate(ats.action_to_string):
+            action_string_chars += string
+            action_string_offset.append(len(action_string_chars))
+        writer.add(action_string_offset, "action-to-action-strings.bin", "uint32")
+        writer.add(action_string_chars, "action-strings.bin", "char")
+
+
+def read_annotation(reader: umbi.TarReader, annotation_label: str, annotation_dict: dict[str, object]):
+    if annotation_dict is None:
+        return
+    path = f"annotations/{annotation_label}"
+    for key, annotation in annotation_dict.items():
+        annotation.data = dict()
+        for applies in annotation.applies_to:
+            filename = f"{path}/{key}/for-{applies}/values.bin"
+            # logging.debug(annotation.type)
+            annotation.data[applies] = reader.read(filename, annotation.type)
+
+
+def write_annotation(writer: umbi.TarWriter, annotation_label: str, annotation_dict: dict[str, object]):
+    if annotation_dict is None:
+        return
+    path = f"annotations/{annotation_label}"
+    for key, annotation in annotation_dict.items():
+        for applies in annotation.applies_to:
+            assert applies in annotation.data
+            filename = f"{path}/{key}/for-{applies}/values.bin"
+            if annotation.type == "int":
+                logging.warning("variable annotation type is int, interpreting as int32")
+                annotation.type = "int32"
+            writer.add(annotation.data[applies], filename, annotation.type)
+
+
+def read_annotation_files(reader: umbi.TarReader, ats: umbi.ExplicitAts):
+    read_annotation(reader, "aps", ats.info.annotations.aps)
+    read_annotation(reader, "rewards", ats.info.annotations.rewards)
+    read_annotation(reader, "variables", ats.info.annotations.variables)
+
+
+def write_annotation_files(writer: umbi.TarWriter, ats: umbi.ExplicitAts):
+    write_annotation(writer, "aps", ats.info.annotations.aps)
+    write_annotation(writer, "rewards", ats.info.annotations.rewards)
+    write_annotation(writer, "variables", ats.info.annotations.variables)
+
+
+def read_umb(tarpath: str) -> umbi.ExplicitAts:
+    """Read ATS from a .umb file."""
+    reader = umbi.TarReader(tarpath)
+    ats = umbi.ExplicitAts()
+    read_index_file(reader, ats)
+    read_state_files(reader, ats)
+    read_branch_files(reader, ats)
+    read_action_files(reader, ats)
+    read_annotation_files(reader, ats)
+    reader.warn_unread_files()
+    # ats.validate()
+    return ats
+
+
+def write_umb(ats: umbi.ExplicitAts, tarpath: str):
+    """Store ATS to a .umb file."""
+    # ats.validate()
+    writer = umbi.TarWriter()
+    write_index_file(writer, ats)
+    write_state_files(writer, ats)
+    write_branch_files(writer, ats)
+    write_action_files(writer, ats)
+    write_annotation_files(writer, ats)
+    writer.write(tarpath)
+
+    # sanity check: try to read the resulting file
+    try:
+        read_umb(tarpath)
+    except Exception as e:
+        logging.warning(f"failed to read the resulted file {tarpath}, printing the error message below:")
+        logging.warning(e)

umbi-0.0.1/umbi.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: umbi
+Version: 0.0.1
+Summary: Library for binary encoding of annotated transition systems
+Author-email: Roman Andriushchenko <roman.andriu@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Roman Andriushchenko
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/randriu/umbi
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: marshmallow
+Requires-Dist: python-magic
+Requires-Dist: tomli
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: toml-sort; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: bumpver; extra == "dev"
+Dynamic: license-file
+
+# umbi
+
+## Installation:
+
+(optional) create and activate a python environment:
+
+```
+$ python -m venv venv
+$ source venv/bin/activate
+```
+
+Install `umbi` via
+```
+(venv) $ pip install umbi
+```
+
+## Running umbi
+
+Examples:
+```
+(venv) $ umbi --import-umb /path/to/input.umb
+(venv) $ umbi --import-umb /path/to/input.umb --export-umb /path/to/output.umb
+(venv) $ umbi --import-umb /path/to/input.umb --export-umb /path/to/output.umb --log-level=DEBUG
+```

umbi-0.0.1/umbi.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+umbi/__init__.py
+umbi/__main__.py
+umbi/ats.py
+umbi/explicit_ats.py
+umbi/io_bytes.py
+umbi/io_json.py
+umbi/io_tar.py
+umbi/io_umb.py
+umbi.egg-info/PKG-INFO
+umbi.egg-info/SOURCES.txt
+umbi.egg-info/dependency_links.txt
+umbi.egg-info/entry_points.txt
+umbi.egg-info/requires.txt
+umbi.egg-info/top_level.txt

umbi-0.0.1/umbi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

umbi-0.0.1/umbi.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+umbi = umbi.__main__:main

umbi-0.0.1/umbi.egg-info/requires.txt

@@ -0,0 +1,12 @@
+marshmallow
+python-magic
+tomli
+
+[dev]
+pytest
+pip-tools
+black
+isort
+toml-sort
+twine
+bumpver

umbi-0.0.1/umbi.egg-info/top_level.txt

@@ -0,0 +1 @@
+umbi