feat: expose solve inputs (#160)

Author: mtth

pyproject.toml

@@ -14,7 +14,7 @@ requires = ['poetry-core']
 build-backend = 'poetry.core.masonry.api'
 
 [tool.poetry]
-version = '0.23.4rc4'
+version = '0.23.5rc1'
 packages = [{include = 'opvious', from = 'src'}]
 
 [tool.poetry.dependencies]

src/opvious/client/handlers.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
+import dataclasses
 import json
 import logging
 from typing import Any, BinaryIO
@@ -259,9 +260,7 @@ async def register_specification(
             tag_name=tag_names[0] if tag_names else None,
         )
 
-    async def _prepare_problem(
-        self, problem: Problem
-    ) -> tuple[Json, ProblemOutline]:
+    async def _prepare_problem(self, problem: Problem) -> _PreparedProblem:
         """Generates solve problem and final outline."""
         # First we fetch the outline to validate/coerce inputs later on
         if isinstance(problem.specification, FormulationSpecification):
@@ -315,7 +314,7 @@ async def _prepare_problem(
             strategy=solve_strategy_to_json(problem.strategy, outline),
             options=solve_options_to_json(problem.options),
         )
-        return (problem, outline)
+        return _PreparedProblem(problem, outline, inputs)
 
     async def serialize_problem(self, problem: Problem) -> Json:
         """Returns a serialized representation of the problem
@@ -326,21 +325,21 @@ async def serialize_problem(self, problem: Problem) -> Json:
         Args:
             problem: :class:`.Problem` instance to serialize
         """
-        problem, _outline = await self._prepare_problem(problem)
-        return problem
+        prepared = await self._prepare_problem(problem)
+        return prepared.data
 
     async def summarize_problem(self, problem: Problem) -> ProblemSummary:
         """Returns summary statistics about a problem without solving it
 
         Args:
             problem: :class:`.Problem` instance to summarize
         """
-        problem, _outline = await self._prepare_problem(problem)
+        prepared = await self._prepare_problem(problem)
         async with self._executor.execute(
             result_type=JsonExecutorResult,
             url="/summarize-problem",
             method="POST",
-            json_data=json_dict(problem=problem),
+            json_data=json_dict(problem=prepared.data),
         ) as res:
             return problem_summary_from_json(res.json_data())
 
@@ -379,12 +378,12 @@ async def format_problem(
 
         .. _LP format: https://web.mit.edu/lpsolve/doc/CPLEX-format.htm
         """
-        problem, _outline = await self._prepare_problem(problem)
+        prepared = await self._prepare_problem(problem)
         async with self._executor.execute(
             result_type=PlainTextExecutorResult,
             url="/format-problem",
             method="POST",
-            json_data=json_dict(problem=problem),
+            json_data=json_dict(problem=prepared.data),
         ) as res:
             lines = []
             async for line in res.lines():
@@ -447,15 +446,15 @@ async def solve(
         See also :meth:`.Client.queue_solve` for an alternative for
         long-running solves.
         """
-        problem, outline = await self._prepare_problem(problem)
+        prepared = await self._prepare_problem(problem)
         if prefer_streaming and self._executor.supports_streaming:
             problem_summary = None
             response_json = None
             async with self._executor.execute(
                 result_type=JsonSeqExecutorResult,
                 url="/solve",
                 method="POST",
-                json_data=json_dict(problem=problem),
+                json_data=json_dict(problem=prepared.data),
             ) as res:
                 async for data in res.json_seq_data():
                     kind = data["kind"]
@@ -498,7 +497,8 @@ async def solve(
             if not problem_summary or not response_json:
                 raise Exception("Streaming solve terminated early")
             solution = solution_from_json(
-                outline=outline,
+                outline=prepared.outline,
+                inputs=prepared.inputs,
                 response_json=response_json,
                 problem_summary=problem_summary,
             )
@@ -507,10 +507,11 @@ async def solve(
                 result_type=JsonExecutorResult,
                 url="/solve",
                 method="POST",
-                json_data=json_dict(problem=problem),
+                json_data=json_dict(problem=prepared.data),
             ) as res:
                 solution = solution_from_json(
-                    outline=outline,
+                    outline=prepared.outline,
+                    inputs=prepared.inputs,
                     response_json=res.json_data(),
                 )
 
@@ -579,13 +580,13 @@ async def queue_solve(
             raise Exception(
                 "Queued solves must have a formulation as specification"
             )
-        problem, _outline = await self._prepare_problem(problem)
+        prepared = await self._prepare_problem(problem)
         async with self._executor.execute(
             result_type=JsonExecutorResult,
             url="/queue-solve",
             method="POST",
             json_data=json_dict(
-                problem=problem,
+                problem=prepared.data,
                 annotations=encode_annotations(annotations or []),
             ),
         ) as res:
@@ -849,3 +850,10 @@ async def _next_page() -> list[QueuedSolve]:
             for solve in solves:
                 yield solve
             limit -= len(solves)
+
+
+@dataclasses.dataclass(frozen=True)
+class _PreparedProblem:
+    data: Json
+    outline: ProblemOutline
+    inputs: SolveInputs

src/opvious/data/solves.py

@@ -177,21 +177,29 @@ class SolveInputs:
     problem_outline: ProblemOutline
     """Target model metadata"""
 
-    raw_parameters: list[Any]
+    raw_parameters: list[Json] = dataclasses.field(repr=False)
     """All parameters in raw format"""
 
-    raw_dimensions: list[Any] | None
+    raw_dimensions: list[Json] | None = dataclasses.field(repr=False)
     """All dimensions in raw format"""
 
-    def parameter(self, label: Label) -> pd.Series:
-        """Returns the parameter for a given label as a pandas Series"""
+    def parameter(self, label: Label, coerce: bool = True) -> pd.DataFrame:
+        """Returns the parameter for a given label as a pandas DataFrame
+
+        The returned dataframe has a `value` column with the parameter's values
+        (0 values may be omitted).
+
+        Args:
+            label: Parameter label to retrieve
+            coerce: Round integral parameters
+        """
         for param in self.raw_parameters:
             if param["label"] == label:
-                entries = param["entries"]
                 outline = self.problem_outline.parameters[label]
-                return pd.Series(
-                    data=(e["value"] for e in entries),
-                    index=_entry_index(entries, outline.bindings),
+                return _entries_dataframe(
+                    param["entries"],
+                    outline.bindings,
+                    round_values=coerce and outline.is_integral,
                 )
         raise Exception(f"Unknown parameter: {label}")
 
@@ -210,10 +218,10 @@ class SolveOutputs:
     problem_outline: ProblemOutline
     """Solved model metadata"""
 
-    raw_variables: list[Any]
+    raw_variables: list[Json] = dataclasses.field(repr=False)
     """All variables in raw format"""
 
-    raw_constraints: list[Any]
+    raw_constraints: list[Json] = dataclasses.field(repr=False)
     """All constraints in raw format"""
 
     def variable(self, label: Label, coerce: bool = True) -> pd.DataFrame:
@@ -230,10 +238,9 @@ def variable(self, label: Label, coerce: bool = True) -> pd.DataFrame:
         for res in self.raw_variables:
             if res["label"] == label:
                 outline = self.problem_outline.variables[label]
-                return _output_dataframe(
+                return _entries_dataframe(
                     res["entries"],
                     outline.bindings,
-                    value_name="value",
                     dual_value_name="reduced_cost",
                     round_values=coerce and outline.is_integral,
                 )
@@ -248,7 +255,7 @@ def constraint(self, label: Label) -> pd.DataFrame:
         """
         for res in self.raw_constraints:
             if res["label"] == label:
-                return _output_dataframe(
+                return _entries_dataframe(
                     res["entries"],
                     self.problem_outline.constraints[label].bindings,
                     value_name="slack",
@@ -257,27 +264,34 @@ def constraint(self, label: Label) -> pd.DataFrame:
         raise Exception(f"Unknown constraint {label}")
 
 
-def _output_dataframe(
+def _entries_dataframe(
     entries: Sequence[Json],
     bindings: Sequence[SourceBinding],
     *,
-    value_name: str,
-    dual_value_name: str,
+    value_name: str = "value",
+    dual_value_name: str | None = None,
     round_values: bool = False,
 ) -> pd.DataFrame:
-    df = pd.DataFrame(
-        data=(
+    if dual_value_name:
+        data = (
             (decode_extended_float(e["value"]), e.get("dualValue"))
             for e in entries
-        ),
-        columns=[value_name, dual_value_name],
+        )
+        columns = [value_name, dual_value_name]
+    else:
+        data = (decode_extended_float(e["value"]) for e in entries)
+        columns = [value_name]
+    df = pd.DataFrame(
+        data=data,
+        columns=columns,
         index=_entry_index(entries, bindings),
     )
-    if df[dual_value_name].isnull().all():
+    if dual_value_name and df[dual_value_name].isnull().all():
         df.drop(dual_value_name, axis=1, inplace=True)
     if round_values:
         df[value_name] = df[value_name].round(0).astype(np.int64)
     df.fillna(0, inplace=True)
+    df.sort_index(inplace=True)
     return df
 
 
@@ -302,6 +316,9 @@ class Solution:
     problem_summary: ProblemSummary
     """Problem summary statistics"""
 
+    inputs: SolveInputs = dataclasses.field(repr=False)
+    """Problem inputs"""
+
     outputs: SolveOutputs | None = dataclasses.field(default=None, repr=False)
     """Solution data, present iff the solution is feasible"""
 
@@ -313,6 +330,7 @@ def feasible(self) -> bool:
 
 def solution_from_json(
     outline: ProblemOutline,
+    inputs: SolveInputs,
     response_json: Any,
     problem_summary: ProblemSummary | None = None,
 ) -> Solution:
@@ -341,6 +359,7 @@ def solution_from_json(
         outcome=outcome,
         problem_summary=problem_summary
         or problem_summary_from_json(response_json["summaries"]["problem"]),
+        inputs=inputs,
         outputs=outputs,
     )
 
@@ -452,9 +471,7 @@ class SolveStrategy:
     @classmethod
     def equally_weighted_sum(cls, sense: ObjectiveSense | None = None) -> Self:
         """Returns a strategy optimizing the sum of all objectives"""
-        return cls(
-            target=collections.defaultdict(lambda: 1), sense=sense
-        )
+        return cls(target=collections.defaultdict(lambda: 1), sense=sense)
 
 
 def solve_strategy_to_json(

tests/client_test.py

@@ -79,7 +79,7 @@ async def test_queue_diet_solve(self):
         assert outcome.objective_value == 33
 
         input_data = await client.fetch_solve_inputs(uuid)
-        costs = input_data.parameter("costPerRecipe")
+        costs = input_data.parameter("costPerRecipe")["value"]
         assert costs.to_dict() == {
             "lasagna": 12,
             "pizza": 15,
@@ -171,6 +171,8 @@ async def test_solve_bounded_feasible(self):
         assert solution.feasible
         assert solution.outcome.optimal
         assert solution.outcome.objective_value == 2
+        assert len(solution.inputs.parameter("bound")) == 1
+        assert len(solution.outputs.variable("target")) == 1
 
     @pytest.mark.asyncio
     async def test_solve_bounded_infeasible(self):