Refactor Equation handling in the uncertainty calculator

Updated the Equation class to use 'latex_name' and 'expression' attributes instead of 'lhs' and 'rhs'. Adjusted related parsing, computation, and rendering logic to accommodate these changes. This refactor enhances clarity in the representation of equations and improves the overall structure of the code. Updated tests to reflect the new attribute names and ensure consistent functionality.

Author: FridrichMethod

README.md

@@ -68,13 +68,18 @@ The core logic is organized by responsibility:
 
 ### 1. Define the Equation
 
-The equation can be defined using the `Equation` class.
+The equation can be defined using the `Equation` class. `latex_name` is the
+rendered result symbol, while `expression` is the internal symbolic formula
+written with variable `name`s.
 
 ```python
 from uncertainty_calculator import Equation
 
 # Define equation
-equation = Equation(lhs=r"\zeta", rhs=r"(K*pi*eta*u*l)/(4*pi*phi*e_0*e_r)")
+equation = Equation(
+    latex_name=r"\zeta",
+    expression=r"(K*pi*eta*u*l)/(4*pi*phi*e_0*e_r)",
+)
 ```
 
 ### 2. Define Variables

src/uncertainty_calculator/compute.py

@@ -26,14 +26,14 @@ def compute(parse_state: ParseState, digits: Digits) -> ComputeState:
     pdv_results: list[tuple[Any, Any, Any]] = []
     for symbol in parse_state.symbols:
         if parse_state.uncertainty_values[symbol]:
-            pdv = simplify(diff(parse_state.equation_right, symbol))
+            pdv = simplify(diff(parse_state.equation_expression, symbol))
             num = pdv.subs(parse_state.output_number)  # type: ignore
             pdv_results.append((symbol, pdv, num))
         else:
             pdv_results.append((symbol, S.Zero, S.Zero))
 
     result_mu = latex_number(
-        parse_state.equation_right.evalf(digits.mu, subs=parse_state.output_number)  # type: ignore
+        parse_state.equation_expression.evalf(digits.mu, subs=parse_state.output_number)  # type: ignore
     )
 
     pdv_nums = [res[2] for res in pdv_results]

src/uncertainty_calculator/parsing.py

@@ -24,8 +24,8 @@ class ParseState:
     uncertainty_values: Mapping[Symbol, Any]
     input_fullunc: list[str]
     input_sigma: list[Any]
-    equation_left: str
-    equation_right: Any
+    equation_latex_name: str
+    equation_expression: Any
 
 
 def parse_inputs(equation: Equation, variables: Variables) -> ParseState:
@@ -77,8 +77,8 @@ def parse_inputs(equation: Equation, variables: Variables) -> ParseState:
     output_value = dict(zip(symbols_parsed + unc_symbols, input_fullmu + input_fullsigma))
     uncertainty_values = dict(zip(symbols_parsed, input_sigma))
 
-    equation_left = equation.lhs
-    equation_right = sympify(equation.rhs, locals=symbol_map)
+    equation_latex_name = equation.latex_name
+    equation_expression = sympify(equation.expression, locals=symbol_map)
 
     return ParseState(
         symbols=symbols_parsed,
@@ -89,6 +89,6 @@ def parse_inputs(equation: Equation, variables: Variables) -> ParseState:
         uncertainty_values=uncertainty_values,
         input_fullunc=input_fullunc,
         input_sigma=input_sigma,
-        equation_left=equation_left,
-        equation_right=equation_right,
+        equation_latex_name=equation_latex_name,
+        equation_expression=equation_expression,
     )

src/uncertainty_calculator/rendering.py

@@ -61,11 +61,11 @@ def _render_equation_def(
     aligned: bool,
 ) -> None:
     separator = "&=" if aligned else "="
-    printer(parse_state.equation_left, end=separator)
-    printer(latex_symbol(parse_state.equation_right, parse_state.output_symbol), end="=")
+    printer(parse_state.equation_latex_name, end=separator)
+    printer(latex_symbol(parse_state.equation_expression, parse_state.output_symbol), end="=")
 
     if options.insert:
-        printer(latex_value(parse_state.equation_right, parse_state.output_value), end="=")
+        printer(latex_value(parse_state.equation_expression, parse_state.output_value), end="=")
 
     res_str = (
         compute_state.result_mu
@@ -93,7 +93,7 @@ def _render_pdvs(
             continue
 
         lhs = (
-            f"\\frac{{\\partial {parse_state.equation_left} }}"
+            f"\\frac{{\\partial {parse_state.equation_latex_name} }}"
             f"{{\\partial {parse_state.output_symbol[symbol]} }}"
         )
         printer(lhs, end=separator)
@@ -110,7 +110,7 @@ def _sigma_symbolic_terms(parse_state: ParseState) -> list[str]:
     for symbol, fullunc in zip(parse_state.symbols, parse_state.input_fullunc):
         if parse_state.uncertainty_values[symbol]:
             terms.append(
-                f"\\left(\\frac{{\\partial {parse_state.equation_left} }}"
+                f"\\left(\\frac{{\\partial {parse_state.equation_latex_name} }}"
                 f"{{\\partial {parse_state.output_symbol[symbol]} }} {fullunc}\\right)^2"
             )
     return terms
@@ -151,15 +151,17 @@ def _render_sigma(
             if options.last_unit is None
             else f"{compute_state.result_sigma}\\ {options.last_unit}"
         )
-        printer(f"\\sigma_{{{parse_state.equation_left}}}&=", end="")
+        printer(f"\\sigma_{{{parse_state.equation_latex_name}}}&=", end="")
         if not options.separate:
             printer(f"{res_str}\\\\\n\\\\")
         else:
             printer(res_str)
         return
 
     symbolic_terms = _sigma_symbolic_terms(parse_state)
-    printer(f"\\sigma_{{{parse_state.equation_left}}}&=\\sqrt{{{'+'.join(symbolic_terms)}}}\\\\")
+    printer(
+        f"\\sigma_{{{parse_state.equation_latex_name}}}&=\\sqrt{{{'+'.join(symbolic_terms)}}}\\\\"
+    )
 
     if options.insert:
         intermediate_terms = _sigma_intermediate_terms(parse_state, compute_state)
@@ -191,12 +193,12 @@ def _render_result_line(
 
     if options.last_unit is None:
         line = (
-            f"{parse_state.equation_left}{separator}"
+            f"{parse_state.equation_latex_name}{separator}"
             f"{compute_state.result_mu} \\pm {compute_state.result_sigma}"
         )
     else:
         line = (
-            f"{parse_state.equation_left}{separator}\\left ({compute_state.result_mu} "
+            f"{parse_state.equation_latex_name}{separator}\\left ({compute_state.result_mu} "
             f"\\pm {compute_state.result_sigma} \\right )\\ {options.last_unit}"
         )
 

src/uncertainty_calculator/types.py

@@ -12,13 +12,15 @@ class Equation:
     """An equation definition for the uncertainty calculator.
 
     Attributes:
-        lhs: The left-hand side of the equation (variable name).
-        rhs: The right-hand side of the equation (expression).
+        latex_name: The rendered left-hand symbol that appears in the final LaTeX.
+        expression: The symbolic right-hand-side expression written using
+            `Variable.name` identifiers. This is only used for computation and
+            does not appear verbatim in the final rendered output.
 
     """
 
-    lhs: str
-    rhs: str
+    latex_name: str
+    expression: str
 
 
 @dataclass

src/uncertainty_calculator/validation.py

@@ -8,7 +8,7 @@
 def validate_inputs(parse_state: ParseState) -> None:
     """Ensure all symbols referenced in the equation are defined by variables."""
     defined_symbols = set(parse_state.symbols)
-    free_symbols = parse_state.equation_right.free_symbols
+    free_symbols = parse_state.equation_expression.free_symbols
 
     for sym in free_symbols:
         if sym not in defined_symbols:

tests/input_parsers.py

@@ -10,12 +10,12 @@
 
 
 def parse_equation(raw_equation: Sequence[str]) -> Equation:
-    """Convert a (lhs, rhs) sequence into an Equation dataclass."""
+    """Convert a (latex_name, expression) sequence into an Equation dataclass."""
     if len(raw_equation) != 2:
-        msg = "Equation must contain exactly two entries (lhs, rhs)."
+        msg = "Equation must contain exactly two entries (latex_name, expression)."
         raise ValueError(msg)
-    lhs, rhs = raw_equation
-    return Equation(lhs=lhs.strip(), rhs=rhs.strip())
+    latex_name, expression = raw_equation
+    return Equation(latex_name=latex_name.strip(), expression=expression.strip())
 
 
 def parse_variables(raw_variables: Iterable[tuple[str, str]]) -> list[Variable]:

tests/test_calculator.py

@@ -27,7 +27,7 @@ def test_calculator_output_matches_legacy(
 ):
     """Refactored calculator should match float-normalized legacy rendering."""
     expected_output = run_legacy_calculator(
-        equation=[equation.lhs, equation.rhs],
+        equation=[equation.latex_name, equation.expression],
         variables=_legacy_variables_from_dataclasses(list(variables)),
         digits=digits,
         last_unit=last_unit,
@@ -60,13 +60,13 @@ def test_run_can_be_called_multiple_times_with_new_inputs():
     )
 
     first_output = calc.run(
-        equation=Equation(lhs="y", rhs="x"),
+        equation=Equation(latex_name="y", expression="x"),
         variables=[Variable(name="x", value=1, uncertainty=0.1, latex_name="x")],
     )
     assert "\\sigma_{x}" in first_output
 
     second_output = calc.run(
-        equation=Equation(lhs="y", rhs="m"),
+        equation=Equation(latex_name="y", expression="m"),
         variables=[Variable(name="m", value=2, uncertainty=0.2, latex_name="m")],
     )
 
@@ -89,7 +89,7 @@ def test_constructor_accepts_only_configuration_arguments():
 
 def test_variable_dataclass_input():
     """Calculator should accept dataclass inputs and return a string output."""
-    equation_obj = Equation(lhs=r"\zeta", rhs=r"K*x")
+    equation_obj = Equation(latex_name=r"\zeta", expression=r"K*x")
     variables_obj = [
         Variable(name="K", value=2.0, uncertainty=0.1, latex_name="K"),
         Variable(name="x", value=3.0, uncertainty=0.2, latex_name="x"),
@@ -109,7 +109,7 @@ def test_variable_dataclass_input():
 
 def test_mixed_input_types():
     """Numeric values provided as float/int should be accepted."""
-    equation = Equation(lhs="y", rhs="x")
+    equation = Equation(latex_name="y", expression="x")
     variables = [Variable(name="x", value=10.5, uncertainty=0.5, latex_name="x")]
     digits = Digits(mu=2, sigma=2)
 

tests/test_compute.py

@@ -11,7 +11,7 @@
 
 
 def _simple_parse_state(value: float, uncertainty: float = 0.1):
-    equation = Equation(lhs="y", rhs="x")
+    equation = Equation(latex_name="y", expression="x")
     variables = [Variable(name="x", value=value, uncertainty=uncertainty, latex_name="x")]
     return parse_inputs(equation, variables)
 

tests/test_parsing.py

@@ -13,8 +13,8 @@ def test_parse_equation_trims_and_builds_dataclass():
     """Whitespace should be stripped when building Equation."""
     raw = ["  A  ", "  B + C  "]
     equation = parse_equation(raw)
-    assert equation.lhs == "A"
-    assert equation.rhs == "B + C"
+    assert equation.latex_name == "A"
+    assert equation.expression == "B + C"
 
 
 def test_parse_equation_invalid_length_raises():
@@ -44,7 +44,7 @@ def test_parse_variables_invalid_definition():
 
 def test_parsing_rejects_duplicate_variable_names():
     """Duplicate variable names should raise a ValueError."""
-    equation = Equation(lhs="y", rhs="x + z")
+    equation = Equation(latex_name="y", expression="x + z")
     variables = [
         Variable(name="x", value=1, uncertainty=0.1, latex_name="x"),
         Variable(name="x", value=2, uncertainty=0.2, latex_name="x_dup"),