FormulaDAG API#

def __init__(
    self,
    formulas: Mapping[str, Any],
    parameters: Mapping[str, Mapping[str, Any]] | None = None,
    notes: Mapping[str, Any] | None = None,
    *,
    legend: bool = True,
    theme: str = "auto",
    **kwargs: Any,
) -> None:
    r"""Create a FormulaDAG widget.

    Args:
        formulas: Mapping from a formula name to its LaTeX, or to a dict
            with ``tex`` plus optional ``symbol`` (what ``\use{name}``
            renders as; defaults to the left-hand side of the first
            top-level ``=``, else the name) and ``label`` (the caption
            under the formula; defaults to the name). Reference another
            formula's output with ``\use{other_name}``. Add ``fn`` to
            compute the formula's value live: a callable whose argument
            names pick parameters or other formulas, e.g.
            ``"fn": lambda d1, vol: d1 - vol``. The value shows in the
            legend and, while you drag or type a number it depends on,
            in place of the formula's symbol and its uses (rounded to
            ``digits``, default 3). It lands in ``outputs``;
            ``committed_outputs`` holds the pre-drag values, like
            ``committed_values``. By default each formula sits one row
            below the deepest formula it uses, so formulas that use
            nothing share the top row. Add ``row`` (0 is the top) to push
            a formula down to at least that row; the formulas that use it
            move down with it.
        parameters: Draggable numbers, shared by every formula. Mark one
            with ``\tangle{name}`` and configure it exactly as in
            ``TangleLatex``: ``value`` is required; optional keys are
            ``min_value``, ``max_value``, ``step``, ``digits``,
            ``display`` (``"number"`` or ``"symbol"``), ``symbol``,
            ``label``, ``pixels_per_step``, and ``color``.
        notes: Plain-language notes, as in ``TangleLatex``. Wrap a part of
            a formula in ``\note{name}{tex}`` and map ``name`` to its text,
            or to a dict with ``text``, ``side`` (``"auto"``, ``"top"``,
            ``"bottom"``) and ``color``. Each note lives in one formula.
        legend: Show a strip under the DAG with one chip per number: its
            symbol, its ``label`` (say what it means there, e.g.
            ``"spot price"``), and its live value. Chips drag and edit
            like the numbers in the formulas, and hovering one lights up
            every place that number appears.
        theme: Color theme: ``"auto"``, ``"light"``, or ``"dark"``.
        **kwargs: Forwarded to ``anywidget.AnyWidget``.
    """
    if theme not in {"auto", "light", "dark"}:
        raise ValueError("theme must be 'auto', 'light', or 'dark'.")
    specs = _normalize_formulas(formulas)
    names = [s["name"] for s in specs]
    symbols = {s["name"]: s["symbol"] for s in specs}

    edges = []
    for spec in specs:
        for used in _USE_RE.findall(spec["tex"]):
            if used == spec["name"]:
                raise ValueError(f"formula {used!r} cannot \\use itself.")
            if used not in symbols:
                raise ValueError(
                    f"formula {spec['name']!r} uses unknown formula {used!r}."
                )
            if [used, spec["name"]] not in edges:
                edges.append([used, spec["name"]])
    cycle = _find_cycle(names, edges)
    if cycle:
        raise ValueError("formulas must not form a cycle: " + " -> ".join(cycle))

    params, normalized_notes = _tangle_and_notes(specs, parameters, notes)
    values = {name: spec["value"] for name, spec in params.items()}
    self._fns = {s["name"]: s["fn"] for s in specs if s["fn"] is not None}
    self._fn_args = _fn_arguments(specs, set(params))
    inputs = _fn_inputs(self._fn_args, set(params))
    outputs, output_errors = self._compute(values)

    # Producers take palette colors in order; formulas nobody uses stay ink.
    # The browser expands \use{...} and the output symbol itself, so it can
    # swap in live values while a number they depend on changes.
    producers = [n for n in names if any(src == n for src, _ in edges)]
    colors = {
        n: dict(_PRODUCER_COLORS[i % len(_PRODUCER_COLORS)]) for i, n in enumerate(producers)
    }
    normalized = []
    for spec in specs:
        split = _split_lhs(spec["tex"])
        lhs, body = (split[0], split[1]) if split else ("", spec["tex"])
        normalized.append(
            {
                "name": spec["name"],
                "lhs": lhs,
                "tex": body,
                "out_note": _whole_note(lhs) if lhs else None,
                "inputs": inputs.get(spec["name"], []),
                "label": spec["label"],
                "symbol": spec["symbol"],
                "digits": spec["digits"],
                "has_fn": spec["fn"] is not None,
                "color": colors.get(spec["name"], dict(_PARAM_COLOR)),
            }
        )

    rows = _formula_rows(names, edges, {s["name"]: s["row"] for s in specs})
    layers, routes, _ = _order_and_route(names, rows, edges)
    super().__init__(
        formulas=normalized,
        layers=[layers[r] for r in sorted(layers) if layers[r]],
        routes=routes,
        parameters=params,
        notes=normalized_notes,
        values=values,
        committed_values=dict(values),
        outputs=outputs,
        committed_outputs=dict(outputs),
        output_errors=output_errors,
        legend=legend,
        theme=theme,
        **kwargs,
    )
    self._edges = [tuple(e) for e in edges]