math-step-to-step 0.2.0__py3-none-any.whl

math_step_to_step/__init__.py

@@ -0,0 +1,10 @@
+"""math-step-to-step: step-by-step solutions for math expressions and equations."""
+from .errors import MathStepError
+from .solver import Solution, evaluate, solve, steps
+from .symbols import prettify, subscript, superscript
+
+__version__ = "0.2.0"
+__all__ = [
+    "steps", "solve", "evaluate", "Solution", "MathStepError",
+    "superscript", "subscript", "prettify", "__version__",
+]

math_step_to_step/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

math_step_to_step/cli.py

@@ -0,0 +1,41 @@
+"""Command line: math-step-to-step "1 + 2 x 3"."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .errors import MathStepError
+from .solver import solve
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="math-step-to-step", description=__doc__)
+    ap.add_argument("expression", nargs="*", help="expression; omit to read lines from stdin")
+    ap.add_argument("-d", "--detailed", action="store_true", help="one operation per step")
+    ap.add_argument("--ascii", action="store_true", help="plain ASCII output")
+    ap.add_argument("--en", action="store_true", help="English messages")
+    ap.add_argument("--style", choices=["auto", "fraction", "decimal"], default="auto")
+    ap.add_argument("-V", "--version", action="version", version=__version__)
+    a = ap.parse_args(argv)
+
+    lines = [" ".join(a.expression)] if a.expression else (l.strip() for l in sys.stdin)
+    code = 0
+    for line in lines:
+        if not line:
+            continue
+        try:
+            sol = solve(line, include_original=True, detailed=a.detailed,
+                        pretty=not a.ascii, style=a.style, lang="en" if a.en else "vi")
+        except MathStepError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            code = 1
+            continue
+        print(sol.steps[0])
+        for s in sol.steps[1:]:
+            print("  →", s)
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

math_step_to_step/context.py

@@ -0,0 +1,23 @@
+"""Options shared by the parser, engine and formatter."""
+from __future__ import annotations
+
+from .errors import LANGS
+
+MAX_LEN = 10_000   # max characters of input
+MAX_BITS = 14_000  # max size of any intermediate number (~4200 digits)
+MAX_DEG = 60       # max polynomial degree
+
+
+class Ctx:
+    __slots__ = ("pretty", "detailed", "lang", "style", "decimal")
+
+    def __init__(self, pretty=True, detailed=False, lang="vi", style="auto"):
+        if lang not in LANGS:
+            raise ValueError(f"lang must be one of {LANGS}")
+        if style not in ("auto", "fraction", "decimal"):
+            raise ValueError("style must be 'auto', 'fraction' or 'decimal'")
+        self.pretty = bool(pretty)
+        self.detailed = bool(detailed)
+        self.lang = lang
+        self.style = style
+        self.decimal = style == "decimal"

math_step_to_step/engine.py

@@ -0,0 +1,413 @@
+"""Step-by-step arithmetic engine.
+
+Each iteration finds every sub-expression that can be evaluated next and
+evaluates them together, giving one displayed step:
+
+* phase A - nodes whose operands are all numbers (e.g. ``2 x 3``, ``(1 + 2)``);
+  anything inside parentheses goes first;
+* phase B - only if phase A found nothing: merge the plain numbers of a sum or
+  product that also holds non-numeric parts (``2 + 3 + x`` -> ``5 + x``).
+"""
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation, localcontext
+from fractions import Fraction
+from math import isqrt
+
+from .context import MAX_BITS
+from .errors import error
+from .nodes import (Eq, Neg, Num, Pi, Pow, Prod, Root, Sqrt, Sum, kids, make_neg,
+                    make_prod, make_sum)
+
+ZERO = Fraction(0)
+ONE = Fraction(1)
+PI = Fraction("3.14159265359")  # the value used for pi
+_RAD_LIMIT = 20_000
+
+
+def chk(v, c):
+    if v.numerator.bit_length() > MAX_BITS or v.denominator.bit_length() > MAX_BITS:
+        raise error(c.lang, "too_big")
+    return v
+
+
+def power(b, e, c):
+    if e.denominator != 1:
+        raise error(c.lang, "int_exp")
+    k = e.numerator
+    if b == 0:
+        if k == 0:
+            raise error(c.lang, "undefined")
+        if k < 0:
+            raise error(c.lang, "div_zero")
+        return ZERO
+    if b != 1 and b != -1:
+        bits = max(b.numerator.bit_length(), b.denominator.bit_length())
+        if abs(k) * (bits - 1) > MAX_BITS:
+            raise error(c.lang, "too_big")
+    return chk(b ** k, c)
+
+
+def _exact_sqrt(v):
+    n, d = v.numerator, v.denominator
+    rn, rd = isqrt(n), isqrt(d)
+    if rn * rn == n and rd * rd == d:
+        return Fraction(rn, rd)
+    return None
+
+
+def _radical(n):
+    """n = k*k*m with m as small as cheaply possible."""
+    k, m, p = 1, n, 2
+    while p * p <= m and p <= _RAD_LIMIT:
+        pp = p * p
+        while m % pp == 0:
+            m //= pp
+            k *= p
+        p += 1 if p == 2 else 2
+    return k, m
+
+
+def _iroot(n, k):
+    """floor(n ** (1/k)) for integers n >= 0, k >= 1."""
+    if n < 2:
+        return n
+    if k >= n.bit_length():
+        return 1
+    x = 1 << ((n.bit_length() + k - 1) // k)
+    while True:
+        y = ((k - 1) * x + n // x ** (k - 1)) // k
+        if y >= x:
+            return x
+        x = y
+
+
+def _radical_k(n, k):
+    """n = c**k * m with m as small as cheaply possible."""
+    if n < 2 or k >= n.bit_length():
+        return 1, n
+    cf, m, p = 1, n, 2
+    while p <= _RAD_LIMIT:
+        pk = p ** k
+        if pk > m:
+            break
+        while m % pk == 0:
+            m //= pk
+            cf *= p
+        p += 1 if p == 2 else 2
+    return cf, m
+
+
+def _mul_div(acc, op, v, c):
+    if op == "*":
+        return chk(acc * v, c)
+    if v == 0:
+        raise error(c.lang, "div_zero")
+    return chk(acc / v, c)
+
+
+# ---------------------------------------------------------------- reductions
+def _red_sum(n, c):
+    terms = n.terms
+    nums = [i for i, (_, x) in enumerate(terms) if type(x) is Num]
+    if len(nums) == len(terms):
+        if c.detailed and len(terms) > 2:
+            (s0, a), (s1, b) = terms[0], terms[1]
+            tot = chk(s0 * a.v + s1 * b.v, c)
+            return make_sum(((1, Num(tot)),) + terms[2:], n.d)
+        tot = ZERO
+        for s, x in terms:
+            tot += x.v if s > 0 else -x.v
+        return Num(chk(tot, c))
+    if len(nums) >= 2:
+        idx = nums[:2] if c.detailed else nums
+        tot = chk(sum((terms[i][0] * terms[i][1].v for i in idx), ZERO), c)
+        first, drop = idx[0], set(idx[1:])
+        new = []
+        for i, (s, x) in enumerate(terms):
+            if i in drop:
+                continue
+            if i == first:
+                if tot != 0:
+                    new.append((1, Num(tot)))
+            else:
+                new.append((s, x))
+        return make_sum(new, n.d)
+    if len(nums) == 1 and terms[nums[0]][1].v == 0:
+        return make_sum([t for i, t in enumerate(terms) if i != nums[0]], n.d)
+    return None
+
+
+def _red_prod(n, c):
+    facs = n.facs
+    if all(type(x) is Num for _, x in facs):
+        if c.detailed and len(facs) > 2:
+            v = _mul_div(facs[0][1].v, facs[1][0], facs[1][1].v, c)
+            return make_prod([("*", Num(v))] + list(facs[2:]), n.d)
+        acc = facs[0][1].v
+        for op, x in facs[1:]:
+            acc = _mul_div(acc, op, x.v, c)
+        return Num(acc)
+    nums = [i for i, (_, x) in enumerate(facs) if type(x) is Num]
+    if len(nums) >= 2:  # merge the numeric factors: 2 x sqrt(2) / 2 -> sqrt(2)
+        idx = nums[:2] if c.detailed else nums
+        m = ONE
+        for i in idx:
+            m = _mul_div(m, facs[i][0], facs[i][1].v, c)
+        if m == 0:
+            return Num(ZERO)
+        first, drop = idx[0], set(idx[1:])
+        new, neg = [], False
+        for i, (op, x) in enumerate(facs):
+            if i in drop:
+                continue
+            if i == first:
+                if m == 1:
+                    continue
+                if m == -1:
+                    neg = True
+                    continue
+                if op == "/" and (1 / m).denominator == 1:
+                    new.append(("/", Num(1 / m)))
+                else:
+                    new.append(("*", Num(m)))
+            else:
+                new.append((op, x))
+        if new[0][0] == "/":
+            new.insert(0, ("*", Num(ONE)))
+        res = make_prod(new, n.d)
+        return make_neg(res, n.d) if neg else res
+    if len(nums) == 1 and all(op == "*" for op, _ in facs):
+        v = facs[nums[0]][1].v
+        if v == 0:
+            return Num(ZERO)
+        if v == 1:
+            return make_prod([f for i, f in enumerate(facs) if i != nums[0]], n.d)
+    return None
+
+
+def _red_sqrt(n, c):
+    v = n.arg.v
+    if v < 0:
+        raise error(c.lang, "sqrt_neg")
+    r = _exact_sqrt(v)
+    if r is not None:
+        return Num(r)
+    if v.denominator == 1:
+        k, m = _radical(v.numerator)
+        if k > 1:
+            return Prod((("*", Num(k)), ("*", Sqrt(Num(m), n.d))), n.d)
+    return None
+
+
+def _red_root(n, c):
+    iv = n.idx.v
+    if iv.denominator != 1 or iv < 1:
+        raise error(c.lang, "bad_index")
+    k = iv.numerator
+    v = n.arg.v
+    if k == 1:
+        return Num(v)
+    sign = 1
+    if v < 0:
+        if k % 2 == 0:
+            raise error(c.lang, "sqrt_neg")
+        sign, v = -1, -v
+    num, den = v.numerator, v.denominator
+    rn, rd = _iroot(num, k), _iroot(den, k)
+    if rn ** k == num and rd ** k == den:
+        return Num(sign * Fraction(rn, rd))
+    if den == 1:
+        cf, m = _radical_k(num, k)
+        if cf > 1:
+            return Prod((("*", Num(sign * cf)), ("*", Root(Num(k), Num(m), n.d))), n.d)
+    return None
+
+
+def _reduce(n, c):
+    t = type(n)
+    if t is Pi:
+        return Num(PI)
+    if t is Root:
+        return _red_root(n, c)
+    if t is Sum:
+        return _red_sum(n, c)
+    if t is Prod:
+        return _red_prod(n, c)
+    if t is Pow:
+        return Num(power(n.base.v, n.exp.v, c))
+    return _red_sqrt(n, c)
+
+
+# ----------------------------------------------------------------- traversal
+def _full(n, out, c):
+    t = type(n)
+    if t is Num:
+        return
+    if t is Sum:
+        if all(type(x) is Num for _, x in n.terms):
+            out.append(n)
+            return
+    elif t is Prod:
+        if all(type(x) is Num for _, x in n.facs):
+            out.append(n)
+            return
+    elif t is Pow:
+        if type(n.base) is Num and type(n.exp) is Num:
+            out.append(n)
+            return
+    elif t is Sqrt:
+        if type(n.arg) is Num:
+            if _red_sqrt(n, c) is not None:
+                out.append(n)
+            return
+    elif t is Root:
+        if type(n.idx) is Num and type(n.arg) is Num:
+            if _red_root(n, c) is not None:
+                out.append(n)
+            return
+    for k in kids(n):
+        _full(k, out, c)
+
+
+def _partial(n, out, c):
+    t = type(n)
+    found = False
+    for k in kids(n):
+        if _partial(k, out, c):
+            found = True
+    if found:
+        return True
+    if (t is Sum and _red_sum(n, c) is not None) or (t is Prod and _red_prod(n, c) is not None):
+        out.append(n)
+        return True
+    return False
+
+
+def _rebuild(n, picks, c):
+    if id(n) in picks:
+        return _reduce(n, c)
+    t = type(n)
+    if t is Sum:
+        new, changed = [], False
+        for s, x in n.terms:
+            y = _rebuild(x, picks, c)
+            changed = changed or y is not x
+            new.append((s, y))
+        return make_sum(new, n.d) if changed else n
+    if t is Prod:
+        new, changed = [], False
+        for op, x in n.facs:
+            y = _rebuild(x, picks, c)
+            if y is not x:
+                changed = True
+                if type(y) is Prod and op == "*":  # (a x b) x c -> a x b x c
+                    new.extend(y.facs)
+                    continue
+            new.append((op, y))
+        if not changed:
+            return n
+        res = make_prod(new, n.d)
+        if n.frac and type(res) is Prod and len(res.facs) == 2 and res.facs[1][0] == "/":
+            res.frac = True
+        return res
+    if t is Pow:
+        b, e = _rebuild(n.base, picks, c), _rebuild(n.exp, picks, c)
+        return n if b is n.base and e is n.exp else Pow(b, e, n.d)
+    if t is Sqrt:
+        a = _rebuild(n.arg, picks, c)
+        return n if a is n.arg else Sqrt(a, n.d)
+    if t is Root:
+        i, a = _rebuild(n.idx, picks, c), _rebuild(n.arg, picks, c)
+        return n if i is n.idx and a is n.arg else Root(i, a, n.d)
+    if t is Neg:
+        a = _rebuild(n.arg, picks, c)
+        return n if a is n.arg else make_neg(a, n.d)
+    if t is Eq:
+        l, r = _rebuild(n.lhs, picks, c), _rebuild(n.rhs, picks, c)
+        return n if l is n.lhs and r is n.rhs else Eq(l, r)
+    return n
+
+
+def _find_pi(n, out):
+    if type(n) is Pi:
+        out.append(n)
+        return
+    for k in kids(n):
+        _find_pi(k, out)
+
+
+def subst_pi(tree, c):
+    """Replace every pi by its numeric value (one step)."""
+    found = []
+    _find_pi(tree, found)
+    if not found:
+        return tree
+    return _rebuild(tree, {id(x) for x in found}, c)
+
+
+def run(tree, c, emit):
+    """Reduce `tree` step by step; call emit(new_tree) after each step."""
+    for _ in range(1_000_000):
+        cands = []
+        _full(tree, cands, c)
+        if not cands:
+            _partial(tree, cands, c)
+        if not cands:
+            return tree
+        if any(x.d > 0 for x in cands):  # parentheses first
+            cands = [x for x in cands if x.d > 0]
+        tree = _rebuild(tree, {id(x) for x in cands}, c)
+        emit(tree)
+    raise error(c.lang, "too_big")
+
+
+# ------------------------------------------------------------ approximations
+_Q = Decimal(1).scaleb(-10)
+
+
+def _ap(n):
+    t = type(n)
+    if t is Num:
+        return Decimal(n.v.numerator) / Decimal(n.v.denominator)
+    if t is Sum:
+        tot = Decimal(0)
+        for s, x in n.terms:
+            tot += _ap(x) if s > 0 else -_ap(x)
+        return tot
+    if t is Prod:
+        acc = _ap(n.facs[0][1])
+        for op, x in n.facs[1:]:
+            acc = acc * _ap(x) if op == "*" else acc / _ap(x)
+        return acc
+    if t is Pow:
+        return _ap(n.base) ** _ap(n.exp)
+    if t is Sqrt:
+        return _ap(n.arg).sqrt()
+    if t is Root:
+        k, x = _ap(n.idx), _ap(n.arg)
+        if x < 0 and k % 2 == 1:
+            return -((-x) ** (1 / k))
+        return x ** (1 / k)
+    if t is Neg:
+        return -_ap(n.arg)
+    raise TypeError(t)
+
+
+def approx(n, c):
+    try:
+        with localcontext() as ctx:
+            ctx.prec = 40
+            return _ap(n)
+    except ArithmeticError:
+        raise error(c.lang, "unsupported", what="approximation") from None
+
+
+def dec_str(d):
+    try:
+        s = format(d.quantize(_Q), "f")
+    except InvalidOperation:
+        return format(d, ".15g")
+    if "." in s:
+        s = s.rstrip("0").rstrip(".")
+    return "0" if s in ("", "-0") else s

math_step_to_step/errors.py

@@ -0,0 +1,74 @@
+"""Exception type and localized messages."""
+from __future__ import annotations
+
+
+class MathStepError(ValueError):
+    """Raised when an expression is invalid or not supported."""
+
+
+_MESSAGES = {
+    "vi": {
+        "empty": "Biểu thức rỗng.",
+        "too_long": "Biểu thức quá dài (tối đa {n} ký tự).",
+        "bad_char": "Ký tự không hợp lệ {c!r} ở vị trí {pos}.",
+        "unexpected": "Không hiểu {tok!r} ở vị trí {pos}.",
+        "unexpected_end": "Biểu thức bị thiếu ở cuối.",
+        "missing_rparen": "Thiếu dấu đóng ngoặc.",
+        "multi_eq": "Chỉ được có một dấu '='.",
+        "div_zero": "Không thể chia cho 0.",
+        "undefined": "0^0 không xác định.",
+        "too_big": "Số quá lớn để tính.",
+        "sqrt_neg": "Không thể lấy căn bậc hai của số âm.",
+        "int_exp": "Chỉ hỗ trợ số mũ nguyên.",
+        "bad_index": "Chỉ số của căn phải là số nguyên dương.",
+        "multi_var": "Chỉ hỗ trợ một biến, nhưng tìm thấy: {names}.",
+        "unsupported": "Chưa hỗ trợ dạng biểu thức này ({what}).",
+        "degree": "Chỉ giải được phương trình bậc 1 và bậc 2.",
+        "nested": "Biểu thức lồng nhau quá sâu.",
+        "has_var": "Biểu thức chứa biến nên không tính ra một số được.",
+        "no_solution": "Phương trình vô nghiệm.",
+        "infinite": "Phương trình có vô số nghiệm.",
+        "delta_neg": "Δ < 0 ⇒ phương trình vô nghiệm (trong tập số thực).",
+        "delta_zero": "Δ = 0 ⇒ phương trình có nghiệm kép.",
+        "delta_pos": "Δ > 0 ⇒ phương trình có hai nghiệm phân biệt.",
+        "true": "Đúng.",
+        "false": "Sai.",
+    },
+    "en": {
+        "empty": "Empty expression.",
+        "too_long": "Expression too long (max {n} characters).",
+        "bad_char": "Invalid character {c!r} at position {pos}.",
+        "unexpected": "Unexpected {tok!r} at position {pos}.",
+        "unexpected_end": "Unexpected end of expression.",
+        "missing_rparen": "Missing closing parenthesis.",
+        "multi_eq": "Only one '=' is allowed.",
+        "div_zero": "Division by zero.",
+        "undefined": "0^0 is undefined.",
+        "too_big": "Number too large to compute.",
+        "sqrt_neg": "Square root of a negative number.",
+        "int_exp": "Only integer exponents are supported.",
+        "bad_index": "The root index must be a positive integer.",
+        "multi_var": "Only one variable is supported, found: {names}.",
+        "unsupported": "Unsupported expression ({what}).",
+        "degree": "Only linear and quadratic equations can be solved.",
+        "nested": "Expression is nested too deeply.",
+        "has_var": "Expression contains a variable and has no numeric value.",
+        "no_solution": "No solution.",
+        "infinite": "Infinitely many solutions.",
+        "delta_neg": "Δ < 0 ⇒ no real solutions.",
+        "delta_zero": "Δ = 0 ⇒ one repeated root.",
+        "delta_pos": "Δ > 0 ⇒ two distinct roots.",
+        "true": "True.",
+        "false": "False.",
+    },
+}
+
+LANGS = tuple(_MESSAGES)
+
+
+def msg(lang: str, key: str, **kw) -> str:
+    return _MESSAGES[lang][key].format(**kw)
+
+
+def error(lang: str, key: str, **kw) -> MathStepError:
+    return MathStepError(msg(lang, key, **kw))