downstream 0.4.2__py2.py3-none-any.whl

downstream/__init__.py

@@ -0,0 +1,15 @@
+"""Top-level package for downstream."""
+
+__author__ = "Matthew Andres Moreno"
+__email__ = "m.more500@gmail.com"
+__version__ = "0.4.2"
+
+
+from . import genome_instrumentation, interop, site_selection_strategy
+
+__all__ = [
+    "interop",
+    "genome_instrumentation",
+    "serialization",
+    "site_selection_strategy",
+]

downstream/downstream/__init__.py

@@ -0,0 +1,4 @@
+from ..genome_instrumentation import *  # noqa: F403
+from ..interop import *  # noqa: F403
+from ..serialization import *  # noqa: F403
+from ..site_selection_strategy import *  # noqa: F403

downstream/genome_instrumentation/_BitSurface.py

@@ -0,0 +1,2 @@
+class BitSurface:
+    """Placeholder."""

downstream/genome_instrumentation/_StructSurface.py

@@ -0,0 +1,2 @@
+class StructSurface:
+    """Placeholder."""

downstream/genome_instrumentation/__init__.py

@@ -0,0 +1,7 @@
+from ._BitSurface import BitSurface
+from ._StructSurface import StructSurface
+
+__all__ = [
+    "BitSurface",
+    "StructSurface",
+]

downstream/interop/__init__.py

@@ -0,0 +1,23 @@
+from . import (
+    _stratum_retention_interop_hybrid_algo as stratum_retention_interop_hybrid_algo,
+)
+from . import (
+    _stratum_retention_interop_steady_algo as stratum_retention_interop_steady_algo,
+)
+from . import (
+    _stratum_retention_interop_tilted_algo as stratum_retention_interop_tilted_algo,
+)
+from . import (
+    _stratum_retention_interop_tilted_sticky_algo as stratum_retention_interop_tilted_sticky_algo,
+)
+from ._make_stratum_retention_policy_from_site_selection_algo import (
+    make_stratum_retention_policy_from_site_selection_algo,
+)
+
+__all__ = [
+    "make_stratum_retention_policy_from_site_selection_algo",
+    "stratum_retention_interop_hybrid_algo",
+    "stratum_retention_interop_steady_algo",
+    "stratum_retention_interop_tilted_algo",
+    "stratum_retention_interop_tilted_sticky_algo",
+]

downstream/interop/_make_stratum_retention_policy_from_site_selection_algo.py

@@ -0,0 +1,278 @@
+import numbers
+import types
+import typing
+
+from hstrat.stratum_retention_strategy.stratum_retention_algorithms._detail import (
+    PolicyCouplerBase,
+    PolicyCouplerFactory,
+    PolicySpecBase,
+)
+import more_itertools as mit
+
+
+class _PolicySpecBase:
+    pass
+
+
+class _GenDropRanksFtorBase:
+    pass
+
+
+class _CalcNumStrataRetainedExactFtorBase:
+    pass
+
+
+class _CalcRankAtColumnIndexFtorBase:
+    pass
+
+
+class _IterRetainedRanksFtorBase:
+    pass
+
+
+class _CalcNumStrataRetainedUpperBoundFtorBase:
+    pass
+
+
+def make_stratum_retention_policy_from_site_selection_algo(
+    site_selection_algo: types.ModuleType,
+) -> PolicyCouplerBase:
+    """Create object infrastructure for a stratum retention policy equivalent
+    to provided surface site selection algorithm."""
+
+    class PolicySpec(PolicySpecBase, _PolicySpecBase):
+        """Contains all policy parameters, if any."""
+
+        _site_selection_algo: types.ModuleType = site_selection_algo
+        _surface_size: int
+
+        def __init__(
+            self: "PolicySpec",
+            surface_size: int,
+        ):
+            """Construct the policy spec.
+
+            Parameters
+            ----------
+            surface_size : int
+                How many sites does surface contain?
+            """
+            assert surface_size > 1
+            self._surface_size = surface_size
+
+        def __eq__(self: "PolicySpec", other: typing.Any) -> bool:
+            return isinstance(other, _PolicySpecBase) and (
+                self._surface_size,
+                self._site_selection_algo,
+            ) == (
+                other._surface_size,
+                other._site_selection_algo,
+            )
+
+        def __repr__(self: "PolicySpec") -> str:
+            return f"""{
+                self.GetAlgoIdentifier()
+            }.{
+                PolicySpec.__qualname__
+            }(surface_size={
+                self._surface_size
+            })"""
+
+        def __str__(self: "PolicySpec") -> str:
+            return f"""{
+                self.GetAlgoTitle()
+            } (surface size: {
+                self._surface_size
+            })"""
+
+        def GetEvalCtor(self: "PolicySpec") -> str:
+            return (
+                "downstream.interop.stratum_retention_interop_"
+                f"{site_selection_algo.__name__}.{self!r}"
+            )
+
+        def GetSurfaceSize(self: "PolicySpec") -> int:
+            return self._surface_size
+
+        @staticmethod
+        def GetAlgoIdentifier() -> str:
+            """Get programatic name for underlying retention algorithm."""
+            return site_selection_algo.__name__
+
+        @staticmethod
+        def GetAlgoTitle() -> str:
+            """Get human-readable name for underlying retention algorithm."""
+            return site_selection_algo.__name__.replace("_", " ")
+
+    class CalcNumStrataRetainedExactFtor(_CalcNumStrataRetainedExactFtorBase):
+        def __init__(
+            self: "CalcNumStrataRetainedExactFtor",
+            policy_spec: typing.Optional[PolicySpec],
+        ) -> None:
+            pass
+
+        def __eq__(
+            self: "CalcNumStrataRetainedExactFtor",
+            other: typing.Any,
+        ) -> bool:
+            return isinstance(other, _CalcNumStrataRetainedExactFtorBase)
+
+        def __call__(
+            self: "CalcNumStrataRetainedExactFtor",
+            policy: PolicyCouplerBase,
+            num_strata_deposited: int,
+        ) -> int:
+            return sum(
+                1 for __ in policy.IterRetainedRanks(num_strata_deposited)
+            )
+
+    class CalcRankAtColumnIndexFtor(_CalcRankAtColumnIndexFtorBase):
+        def __init__(
+            self: "CalcRankAtColumnIndexFtor",
+            policy_spec: typing.Optional[PolicySpec],
+        ) -> None:
+            pass
+
+        def __eq__(
+            self: "CalcRankAtColumnIndexFtor",
+            other: typing.Any,
+        ) -> bool:
+            return isinstance(other, _CalcRankAtColumnIndexFtorBase)
+
+        def __call__(
+            self: "CalcRankAtColumnIndexFtor",
+            policy: PolicyCouplerBase,
+            index: int,
+            num_strata_deposited: int,
+        ) -> int:
+            if (
+                not 0
+                <= index
+                < policy.CalcNumStrataRetainedExact(num_strata_deposited)
+            ):
+                raise IndexError
+            res = mit.nth(
+                policy.IterRetainedRanks(num_strata_deposited), index
+            )
+            assert res is not None
+            return res
+
+    class GenDropRanksFtor(_GenDropRanksFtorBase):
+        def __init__(
+            self: "GenDropRanksFtor",
+            policy_spec: typing.Optional[PolicySpec],
+        ) -> None:
+            pass
+
+        def __eq__(
+            self: "GenDropRanksFtor",
+            other: typing.Any,
+        ) -> bool:
+            return isinstance(other, _GenDropRanksFtorBase)
+
+        def __call__(
+            self: "GenDropRanksFtor",
+            policy: PolicyCouplerBase,
+            num_stratum_depositions_completed: int,
+            retained_ranks: typing.Optional[typing.Iterable[int]] = None,
+        ) -> typing.Iterator[int]:
+            # convert for compat with numpy dtypes
+            assert isinstance(
+                num_stratum_depositions_completed, numbers.Integral
+            )
+            num_stratum_depositions_completed = int(
+                num_stratum_depositions_completed,
+            )
+
+            if num_stratum_depositions_completed == 0:
+                return
+
+            algo = site_selection_algo
+            surface_size = policy.GetSpec().GetSurfaceSize()
+
+            target_site = algo.pick_deposition_site(
+                num_stratum_depositions_completed, surface_size
+            )
+            target_rank = algo.calc_resident_deposition_rank(
+                target_site, surface_size, num_stratum_depositions_completed
+            )
+            if target_rank != 0:
+                yield target_rank
+                return
+            elif 0 not in algo.iter_resident_deposition_ranks(
+                surface_size,
+                num_stratum_depositions_completed + 1,
+            ):
+                yield 0
+                return
+
+    class IterRetainedRanksFtor(_IterRetainedRanksFtorBase):
+        def __init__(
+            self: "IterRetainedRanksFtor",
+            policy_spec: typing.Optional[PolicySpec],
+        ) -> None:
+            pass
+
+        def __eq__(
+            self: "IterRetainedRanksFtor",
+            other: typing.Any,
+        ) -> bool:
+            return isinstance(other, _IterRetainedRanksFtorBase)
+
+        def __call__(
+            self: "IterRetainedRanksFtor",
+            policy: PolicyCouplerBase,
+            num_strata_deposited: int,
+        ) -> typing.Iterator[int]:
+            # convert for compat with numpy dtypes
+            assert isinstance(num_strata_deposited, numbers.Integral)
+            num_strata_deposited = int(num_strata_deposited)
+
+            if num_strata_deposited == 0:
+                return
+            algo = site_selection_algo
+            surface_size = policy.GetSpec().GetSurfaceSize()
+            ranks = sorted(
+                algo.iter_resident_deposition_ranks(
+                    surface_size,
+                    num_strata_deposited,
+                )
+            )
+            last_zero = ranks.count(0) - (ranks[0] == 0)
+            assert 0 <= last_zero < len(ranks)
+            yield from ranks[last_zero:]
+
+    class CalcNumStrataRetainedUpperBoundFtor(
+        _CalcNumStrataRetainedUpperBoundFtorBase,
+    ):
+        def __init__(
+            self: "CalcNumStrataRetainedUpperBoundFtor",
+            policy_spec: typing.Optional[PolicySpec],
+        ) -> None:
+            pass
+
+        def __eq__(
+            self: "CalcNumStrataRetainedUpperBoundFtor",
+            other: typing.Any,
+        ) -> bool:
+            return isinstance(other, _CalcNumStrataRetainedUpperBoundFtorBase)
+
+        def __call__(
+            self: "CalcNumStrataRetainedUpperBoundFtor",
+            policy: PolicyCouplerBase,
+            num_strata_deposited: int,
+        ) -> typing.Iterator[int]:
+            surface_size = policy.GetSpec().GetSurfaceSize()
+            return min(
+                num_strata_deposited,
+                surface_size,
+            )
+
+    return PolicyCouplerFactory(
+        policy_spec_t=PolicySpec,
+        gen_drop_ranks_ftor_t=GenDropRanksFtor,
+        calc_num_strata_retained_exact_ftor_t=CalcNumStrataRetainedExactFtor,
+        calc_rank_at_column_index_ftor_t=CalcRankAtColumnIndexFtor,
+        iter_retained_ranks_ftor_t=IterRetainedRanksFtor,
+        calc_num_strata_retained_upper_bound_ftor_t=CalcNumStrataRetainedUpperBoundFtor,
+    )

downstream/interop/_stratum_retention_interop_hybrid_algo.py

@@ -0,0 +1,14 @@
+from ..site_selection_strategy.site_selection_algorithms import (
+    hybrid_algo as _site_selection_algo,
+)
+from ._make_stratum_retention_policy_from_site_selection_algo import (
+    make_stratum_retention_policy_from_site_selection_algo,
+)
+
+Policy = make_stratum_retention_policy_from_site_selection_algo(
+    _site_selection_algo
+)
+PolicySpec = Policy.policy_spec_t
+
+# prevent name leakage
+del make_stratum_retention_policy_from_site_selection_algo

downstream/interop/_stratum_retention_interop_steady_algo.py

@@ -0,0 +1,14 @@
+from ..site_selection_strategy.site_selection_algorithms import (
+    steady_algo as _site_selection_algo,
+)
+from ._make_stratum_retention_policy_from_site_selection_algo import (
+    make_stratum_retention_policy_from_site_selection_algo,
+)
+
+Policy = make_stratum_retention_policy_from_site_selection_algo(
+    _site_selection_algo
+)
+PolicySpec = Policy.policy_spec_t
+
+# prevent name leakage
+del make_stratum_retention_policy_from_site_selection_algo

downstream/interop/_stratum_retention_interop_tilted_algo.py

@@ -0,0 +1,14 @@
+from ..site_selection_strategy.site_selection_algorithms import (
+    tilted_algo as _site_selection_algo,
+)
+from ._make_stratum_retention_policy_from_site_selection_algo import (
+    make_stratum_retention_policy_from_site_selection_algo,
+)
+
+Policy = make_stratum_retention_policy_from_site_selection_algo(
+    _site_selection_algo,
+)
+PolicySpec = Policy.policy_spec_t
+
+# prevent name leakage
+del make_stratum_retention_policy_from_site_selection_algo

downstream/interop/_stratum_retention_interop_tilted_sticky_algo.py

@@ -0,0 +1,14 @@
+from ..site_selection_strategy.site_selection_algorithms import (
+    tilted_sticky_algo as _site_selection_algo,
+)
+from ._make_stratum_retention_policy_from_site_selection_algo import (
+    make_stratum_retention_policy_from_site_selection_algo,
+)
+
+Policy = make_stratum_retention_policy_from_site_selection_algo(
+    _site_selection_algo,
+)
+PolicySpec = Policy.policy_spec_t
+
+# prevent name leakage
+del make_stratum_retention_policy_from_site_selection_algo

downstream/pylib/Literal.py

@@ -0,0 +1,4 @@
+try:
+    from typing import Literal  # noqa: F401
+except ImportError:
+    from typing_extensions import Literal  # noqa: F401

downstream/pylib/__init__.py

@@ -0,0 +1,69 @@
+from . import (
+    hanoi,
+    longevity_ordering_alternating,
+    longevity_ordering_descending,
+    longevity_ordering_naive,
+    longevity_ordering_piecewise_ascending,
+    oeis,
+    site_selection_eval,
+    site_selection_viz,
+)
+from .Literal import Literal
+from .bit_ceil import bit_ceil
+from .bit_count_immediate_zeros import bit_count_immediate_zeros
+from .bit_count_leading_ones import bit_count_leading_ones
+from .bit_decode_gray import bit_decode_gray
+from .bit_drop_msb import bit_drop_msb
+from .bit_encode_gray import bit_encode_gray
+from .bit_floor import bit_floor
+from .bit_invert import bit_invert
+from .bit_reverse import bit_reverse
+from .calc_dyadic_lcm_upper_bound import calc_dyadic_lcm_upper_bound
+from .count_factors_of_2 import count_factors_of_2
+from .enforce_typing import enforce_typing
+from .fast_pow2_divide import fast_pow2_divide
+from .fast_pow2_mod import fast_pow2_mod
+from .get_powersof2triangle_val_at_index import (
+    get_powersof2triangle_val_at_index,
+)
+from .jupyter_hide_toggle import jupyter_hide_toggle
+from .log_args_and_result import log_args_and_result
+from .modulo import modulo
+from .prepend_cmap_with_color import prepend_cmap_with_color
+from .round_to_one_sigfig import round_to_one_sigfig
+from .sign import sign
+from .tee_release import tee_release
+
+__all__ = [
+    "bit_ceil",
+    "bit_count_immediate_zeros",
+    "bit_count_leading_ones",
+    "bit_drop_msb",
+    "bit_decode_gray",
+    "bit_invert",
+    "bit_encode_gray",
+    "bit_floor",
+    "bit_reverse",
+    "calc_dyadic_lcm_upper_bound",
+    "count_factors_of_2",
+    "enforce_typing",
+    "fast_pow2_divide",
+    "fast_pow2_mod",
+    "get_powersof2triangle_val_at_index",
+    "jupyter_hide_toggle",
+    "Literal",
+    "log_args_and_result",
+    "modulo",
+    "prepend_cmap_with_color",
+    "round_to_one_sigfig",
+    "hanoi",
+    "longevity_ordering_naive",
+    "longevity_ordering_alternating",
+    "longevity_ordering_piecewise_ascending",
+    "longevity_ordering_descending",
+    "oeis",
+    "sign",
+    "site_selection_eval",
+    "site_selection_viz",
+    "tee_release",
+]

downstream/pylib/bit_ceil.py

@@ -0,0 +1,11 @@
+def bit_ceil(n: int) -> int:
+    """Calculate the smallest power of 2 not smaller than n."""
+    # adapted from https://github.com/mmore500/hstrat/blob/e9c2994c7a6514162f1ab685d88c374372dc1cf0/hstrat/_auxiliary_lib/_bit_ceil.py
+    assert n >= 0
+    if n:
+        # see https://stackoverflow.com/a/14267825/17332200
+        exp = (n - 1).bit_length()
+        res = 1 << exp
+        return res
+    else:
+        return 1

downstream/pylib/bit_count_immediate_zeros.py

@@ -0,0 +1,10 @@
+from .bit_drop_msb import bit_drop_msb
+
+
+def bit_count_immediate_zeros(x: int) -> int:
+    """Count the number of zeros immediately following the first binary digit
+    of x.
+
+    Equivalent to [OEIS:A290255](https://oeis.org/A290255).
+    """
+    return x.bit_length() - bit_drop_msb(x).bit_length() - bool(x)

downstream/pylib/bit_count_leading_ones.py

@@ -0,0 +1,18 @@
+from .bit_invert import bit_invert
+
+
+def bit_count_leading_ones(n: int) -> int:
+    """Count the number of consecutive leading 1's in the binary representation
+    of an integer.
+
+    Examples
+    --------
+    >>> bit_count_leading_ones(0b11110000)
+    4
+    >>> bit_count_leading_ones(0b1111)
+    4
+    >>> bit_count_leading_ones(0b100000000)
+    1
+    """
+    # see https://stackoverflow.com/a/77756334/17332200
+    return n.bit_length() - bit_invert(n).bit_length()

downstream/pylib/bit_decode_gray.py

@@ -0,0 +1,8 @@
+def bit_decode_gray(n: int) -> int:
+    x = n
+    e = 1
+    while x:
+        x = n >> e
+        e <<= 1
+        n ^= x
+    return n

downstream/pylib/bit_drop_msb.py

@@ -0,0 +1,6 @@
+from .bit_floor import bit_floor
+
+
+def bit_drop_msb(n: int) -> int:
+    """Drop most significant bit from binary representation of integer n."""
+    return n & (~bit_floor(n))

downstream/pylib/bit_encode_gray.py

@@ -0,0 +1,7 @@
+def bit_encode_gray(n: int) -> int:
+    """Encode an integer using Gray code.
+
+    Gray code is a binary numeral system where two successive values differ in
+    only one bit. See <https://en.wikipedia.org/wiki/Gray_code>.
+    """
+    return n ^ (n >> 1)

downstream/pylib/bit_floor.py

@@ -0,0 +1,8 @@
+def bit_floor(n: int) -> int:
+    """Calculate the largest power of two not greater than n.
+
+    If zero, returns zero.
+    """
+    # adapted from https://github.com/mmore500/hstrat/blob/e9c2994c7a6514162f1ab685d88c374372dc1cf0/hstrat/_auxiliary_lib/_bit_floor.py
+    mask = 1 << (n >> 1).bit_length()
+    return n & mask

downstream/pylib/bit_invert.py

@@ -0,0 +1,7 @@
+def bit_invert(n: int) -> int:
+    """Calculate the bitwise inverse of n.
+
+    Doesn't do funky stuff with sign bits, like Python's built-in bitwise not.
+    """
+    mask = (1 << n.bit_length()) - 1
+    return n ^ mask

downstream/pylib/bit_reverse.py

@@ -0,0 +1,9 @@
+# adapted from https://stackoverflow.com/a/37579581
+def bit_reverse(n: int) -> int:
+    """Reverse the bit sequence of an integer."""
+    assert n >= 0
+    res = 0
+    while n:
+        res = (res << 1) + (n & 1)
+        n >>= 1
+    return res

downstream/pylib/calc_dyadic_lcm_upper_bound.py

@@ -0,0 +1,25 @@
+from .count_factors_of_2 import count_factors_of_2
+
+
+def calc_dyadic_lcm_upper_bound(a: int, b: int) -> int:
+    """Calculate an upper bound of the least common multiple (LCM) of two
+    integers as their product less their common factors of 2.
+
+    Returns
+    -------
+    int
+        The upper bound of the LCM of `a` and `b` obtained by removing
+        the common factors of 2.
+
+    Examples
+    --------
+    >>> calc_dyadic_lcm_upper_bound(12, 18)
+    108
+    >>> calc_dyadic_lcm_upper_bound(13, 17)
+    221
+    """
+    assert a
+    assert b
+    least_factors_of_2 = min(count_factors_of_2(a), count_factors_of_2(b))
+    res = a * b >> least_factors_of_2
+    return res

downstream/pylib/count_factors_of_2.py

@@ -0,0 +1,19 @@
+def count_factors_of_2(number: int) -> int:
+    """Counts the number of factors of 2 in a given integer using bitwise operations.
+
+    Returns
+    -------
+    int
+        The number of factors of 2.
+
+    Examples
+    --------
+    >>> count_factors_of_2(12)
+    2
+    >>> count_factors_of_2(1024)
+    10
+    """
+    if number == 0:
+        return 0
+    else:
+        return (number & -number).bit_length() - 1

downstream/pylib/enforce_typing.py

@@ -0,0 +1,41 @@
+from functools import wraps
+from typing import Any, Callable, get_type_hints
+
+
+def enforce_typing(func: Callable) -> Callable:
+    """Enforces argument and return types on wrapped function at runtime.
+
+    Raises TypeError for detected violations.
+    """
+    # Get type hints
+    hints = get_type_hints(func)
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Check argument types
+        arg_names = list(func.__annotations__.keys())
+        for arg_name, value in zip(arg_names, args):
+            expected_type = hints.get(arg_name)
+            if expected_type and not isinstance(value, expected_type):
+                actual_type = type(value)
+                raise TypeError(
+                    f"Argument '{arg_name}' must be of type {expected_type}, "
+                    f"but got {actual_type} with value {value}",
+                )
+
+        # Call the original function
+        result = func(*args, **kwargs)
+
+        # Check return type
+        if "return" in hints:
+            expected_return_type = hints["return"]
+            if not isinstance(result, expected_return_type):
+                actual_return_type = type(result)
+                raise TypeError(
+                    f"Return value must be of type {expected_return_type}, "
+                    f"but got {actual_return_type} with value {result}",
+                )
+
+        return result
+
+    return wrapper