luminarycloud 0.22.3__py3-none-any.whl → 0.23.1__py3-none-any.whl

luminarycloud/pipelines/user_code_validation.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import ast
+import builtins
+import inspect
+import symtable
+import textwrap
+import types
+from dataclasses import dataclass
+from typing import Callable, Iterable, Union
+
+
+PROVIDED_GLOBALS = {"luminarycloud", "lc"}
+ALL_ALLOWED_GLOBALS = set(dir(builtins)) | PROVIDED_GLOBALS
+
+
+@dataclass(frozen=True)
+class ValidatedFunction:
+    """Result of validation."""
+
+    source: str
+    entrypoint: str
+
+
+class FunctionValidationError(ValueError):
+    pass
+
+
+def _param_name_set(fn_node: ast.FunctionDef | ast.AsyncFunctionDef) -> frozenset[str]:
+    """
+    Return the set of parameter names for the function, excluding kwargs.
+    """
+    a = fn_node.args
+    if a.posonlyargs:
+        raise FunctionValidationError("Positional-only arguments are not supported.")
+    if a.vararg:
+        raise FunctionValidationError("Variable-length arguments are not supported.")
+    return frozenset(x.arg for x in a.args)
+
+
+def validate_portable_top_level_function(
+    fn: Callable | str,
+    *,
+    must_have_params: set[str],
+    can_have_params: set[str],
+) -> ValidatedFunction:
+    """
+    Validate that `fn` is a function which has no freevars and no globals beyond builtins, and
+    comports with the given must_have_params and can_have_params.
+
+    Raises FunctionValidationError on any violation.
+    """
+
+    if isinstance(fn, str):
+        src = textwrap.dedent(fn)
+    else:
+        try:
+            source_lines, _ = inspect.getsourcelines(fn)
+        except (OSError, IOError, TypeError) as exc:
+            raise ValueError(f"Unable to retrieve source for function: {exc}") from exc
+        # Drop decorator lines (everything before the `def`)
+        for i, line in enumerate(source_lines):
+            if line.lstrip().startswith("def "):
+                source_lines = source_lines[i:]
+                break
+        src = textwrap.dedent("".join(source_lines))
+    if not src.endswith("\n"):
+        src += "\n"
+    parsed = ast.parse(src, filename="<string>", mode="exec")
+    body = parsed.body
+
+    if len(body) != 1 or not isinstance(body[0], ast.FunctionDef):
+        found = [type(n).__name__ for n in body]
+        raise FunctionValidationError(
+            "Code must contain exactly one top-level function definition and nothing else at the top level. "
+            f"Found top-level items: {found}"
+        )
+
+    fn_node = body[0]
+    fn_name = fn_node.name
+
+    actual_params = _param_name_set(fn_node)
+
+    if actual_params - can_have_params != must_have_params:
+        raise FunctionValidationError(
+            f"Parameter mismatch for function {fn_name!r}.\n"
+            f"Your function takes: {sorted(actual_params)}\n"
+            f"It must take all stage inputs and params: {sorted(must_have_params)}\n"
+            f"It can also take these implicit params: {sorted(can_have_params)}\n"
+            f"Your function's extra params are: {sorted(actual_params - must_have_params - can_have_params)}\n"
+            f"Your function's missing params are: {sorted(must_have_params - actual_params)}"
+        )
+
+    st = symtable.symtable(src, filename="<string>", compile_type="exec")
+
+    # Find the function's symbol table (top-level child)
+    fn_st = None
+    for child in st.get_children():
+        if child.get_type() == "function" and child.get_name() == fn_name:
+            fn_st = child
+            break
+    if fn_st is None:
+        # This should not happen given the AST check, but keep it explicit.
+        raise FunctionValidationError(f"Could not locate symbol table for {fn_name!r}")
+
+    freevars = [s.get_name() for s in fn_st.get_symbols() if s.is_free()]
+    if freevars:
+        raise FunctionValidationError(
+            f"Function {fn_name!r} closes over nonlocals/free variables: {sorted(set(freevars))}"
+        )
+
+    globals_used = [s.get_name() for s in fn_st.get_symbols() if s.is_global()]
+    disallowed_globals = sorted({g for g in globals_used if g not in ALL_ALLOWED_GLOBALS})
+
+    if disallowed_globals:
+        raise FunctionValidationError(
+            "RunScript functions must not rely on non-local variables, including imports. All "
+            f"modules your script needs (except {', '.join(PROVIDED_GLOBALS)}) must be imported in "
+            f"the function body. Found non-local variables: {', '.join(disallowed_globals)}"
+        )
+
+    return ValidatedFunction(source=src, entrypoint=fn_name)

luminarycloud/project.py

@@ -30,7 +30,6 @@ from ._helpers import (
     list_inference_jobs,
     SurfaceForInference,
 )
-from ._helpers.warnings import deprecated
 from ._proto.api.v0.luminarycloud.geometry import geometry_pb2 as geometrypb
 from ._proto.api.v0.luminarycloud.mesh import mesh_pb2 as meshpb
 from ._proto.api.v0.luminarycloud.named_variable_set import (
@@ -833,19 +832,6 @@ def get_project(
     return Project(res.project)
 
 
-@deprecated("Use iterate_projects() instead.", "0.10.1")
-def list_projects() -> list[Project]:
-    """
-    List projects accessible by the user.
-
-    .. deprecated:: 0.10.1
-        `list_projects()` will be removed in v0.11.0, it is replaced by
-        `iterate_projects()` because the latter provides a more efficient
-        way to fetch projects.
-    """
-    return list(iterate_projects())
-
-
 class ProjectIterator(PaginationIterator[Project]):
     """Iterator class for projects that provides length hint."""
 

luminarycloud/simulation.py

@@ -6,7 +6,6 @@ from typing import Optional
 from ._client import get_default_client
 from ._helpers._timestamp_to_datetime import timestamp_to_datetime
 from ._helpers._wait_for_simulation import wait_for_simulation
-from ._helpers.warnings import deprecated
 from ._proto.api.v0.luminarycloud.common import common_pb2 as commonpb
 from ._proto.api.v0.luminarycloud.simulation import simulation_pb2 as simulationpb
 from ._proto.api.v0.luminarycloud.solution import solution_pb2 as solutionpb
@@ -16,14 +15,14 @@ from ._wrapper import ProtoWrapper, ProtoWrapperBase
 from .enum import (
     AveragingType,
     CalculationType,
+    MomentConventionType,
     QuantityType,
     ResidualNormalization,
-    MomentConventionType,
     SimulationStatus,
     Vector3Component,
 )
+from .outputs import ForceOutputDefinition, SurfaceAverageOutputDefinition
 from .outputs.stopping_conditions import StoppingConditionStatusResult
-from .simulation_param import SimulationParam
 from .reference_values import ReferenceValues
 from .simulation_param import SimulationParam
 from .solution import Solution
@@ -74,7 +73,7 @@ class Simulation(ProtoWrapperBase):
     def update(
         self,
         *,
-        name: str = None,
+        name: Optional[str] = None,
     ) -> None:
         """
         Update/Edit simulation attributes.
@@ -184,7 +183,7 @@ class Simulation(ProtoWrapperBase):
         quantity_type: QuantityType,
         surface_ids: list[str],
         *,
-        reference_values: ReferenceValues = None,
+        reference_values: Optional[ReferenceValues] = None,
         calculation_type: CalculationType = CalculationType.AGGREGATE,
         frame_id: str = "",
         force_direction: Optional[Vector3Like] = None,
@@ -279,6 +278,44 @@ class Simulation(ProtoWrapperBase):
         res = get_default_client().GetSimulationSurfaceQuantityOutput(req)
         return _DownloadedTextFile(res.csv_file)
 
+    def download_output_from_definition(
+        self,
+        output_definition: ForceOutputDefinition | SurfaceAverageOutputDefinition,
+        *,
+        reference_values: Optional[ReferenceValues] = None,
+    ):
+        """
+        Downloads surface outputs (e.g. lift, drag, ...) in csv format based on an output
+        definition.
+
+        Unless `reference_values` is explicitly passed, the Simulation's reference values -- i.e.
+        the ones specified when the Simulation was created -- will be used for computing
+        non-dimensional output quantities. While the Luminary Cloud UI lets you update the reference
+        values on a Simulation result after it has run, those updates only affect the output
+        calculations seen in the UI, they have no effect on the ones retrieved by this method.
+
+        Parameters
+        ----------
+        output_definition : ForceOutputDefinition | SurfaceAverageOutputDefinition
+            Output definition
+
+        Other Parameters
+        ----------------
+        reference_values : ReferenceValues, optional
+            Reference values used for computing forces, moments, and other non-dimensional output
+            quantities. If not provided, the simulation's reference values will be used, i.e., the
+            ones specified when the simulation was created.
+        """
+        req = simulationpb.GetSimulationOutputFromDefinitionRequest(
+            id=self.id,
+            output_definition=output_definition._to_proto(),
+            reference_values=(
+                reference_values._to_proto() if reference_values else ReferenceValues()._to_proto()
+            ),
+        )
+        res = get_default_client().GetSimulationOutputFromDefinition(req)
+        return _DownloadedTextFile(res.csv_file)
+
     def delete(self) -> None:
         """
         Delete the simulation.
@@ -349,12 +386,6 @@ class Simulation(ProtoWrapperBase):
         res = get_default_client().GetStoppingConditionStatus(req)
         return StoppingConditionStatusResult._from_proto(res)
 
-    @deprecated(
-        "Use get_parameters() instead. This method will be removed in a future release.",
-    )
-    def get_simulation_param(self) -> SimulationParam:
-        return self.get_parameters()
-
     # This is used by the assistant for the SDK Code shown in the Results tab.
     def _to_code(self) -> str:
         return f"""# This code shows how to modify the parameters of the current simulation to create a new one.

luminarycloud/simulation_param.py

@@ -247,63 +247,6 @@ class SimulationParam(_SimulationParam):
             )
         )
 
-    def configure_adjoint_surface_output(
-        self,
-        quantity_type: QuantityType,
-        surface_ids: list[str],
-        *,
-        reference_values: ReferenceValues = None,
-        frame_id: str = "",
-        force_direction: Optional[Vector3Like] = None,
-        moment_center: Optional[Vector3Like] = None,
-        moment_convention_type: MomentConventionType = MomentConventionType.BODY_FRAME,
-        averaging_type: AveragingType = AveragingType.UNSPECIFIED,
-    ) -> None:
-        """
-        Helper to configure the surface output differentiated by the adjoint solver.
-        See Simulation.download_surface_output() for details on the input parameters.
-
-        .. warning:: This feature is experimental and may change or be removed without notice.
-        """
-        self.adjoint = self.adjoint or Adjoint()
-        self.adjoint._output = outputpb.Output()
-        self.adjoint._output.quantity = quantity_type.value
-        self.adjoint._output.in_surfaces.extend(surface_ids)
-        self.adjoint._output.frame_id = frame_id
-        if QuantityType._is_average(quantity_type):
-            if averaging_type == AveragingType.UNSPECIFIED:
-                self.adjoint._output.surface_average_properties.averaging_type = (
-                    SpaceAveragingType.NO_AVERAGING.value
-                )
-            elif averaging_type == AveragingType.AREA:
-                self.adjoint._output.surface_average_properties.averaging_type = (
-                    SpaceAveragingType.AREA.value
-                )
-            elif averaging_type == AveragingType.MASS_FLOW:
-                self.adjoint._output.surface_average_properties.averaging_type = (
-                    SpaceAveragingType.MASS_FLOW.value
-                )
-        elif QuantityType._is_force(quantity_type):
-            self.adjoint._output.force_properties.CopyFrom(
-                outputpb.ForceProperties(
-                    force_dir_type=(
-                        outputpb.FORCE_DIRECTION_BODY_ORIENTATION_AND_FLOW_DIR
-                        if quantity_type._has_tag(quantityoptspb.TAG_AUTO_DIRECTION)
-                        else outputpb.FORCE_DIRECTION_CUSTOM
-                    ),
-                    force_direction=(
-                        _to_vector3_ad_proto(force_direction) if force_direction else None
-                    ),
-                    moment_center=_to_vector3_ad_proto(moment_center) if moment_center else None,
-                    moment_convention_type=moment_convention_type.value,
-                )
-            )
-        else:
-            raise ValueError("Invalid QuantityType.")
-
-        if reference_values is not None:
-            self.reference_values = reference_values
-
     def __repr__(self) -> str:
         return pformat(vars(self), compact=True, sort_dicts=True)
 
@@ -334,11 +277,6 @@ from luminarycloud import outputs, SimulationParam, EntityIdentifier
         code += self._to_code_helper("obj", hide_defaults, use_tmp_objs).replace(
             "luminarycloud.simulation_param.SimulationParam()", "luminarycloud.SimulationParam()", 1
         )
-        if self.adjoint.primal_simulation_id != "":
-            code += """
-# TODO(USER): Select appropriate parameters to configure the adjoint output.
-obj.configure_adjoint_output("...")
-"""
         return code
 
     def find_parameter(self, parameter: str) -> None:

luminarycloud/simulation_template.py

@@ -8,7 +8,6 @@ from difflib import Differ
 from .enum import (
     TableType,
 )
-from ._helpers.warnings import deprecated
 from ._client import get_default_client
 from ._helpers._simulation_params_from_json import simulation_params_from_json_path
 from ._helpers._timestamp_to_datetime import timestamp_to_datetime
@@ -180,15 +179,6 @@ class SimulationTemplate(ProtoWrapperBase):
         """
         return SimulationParam.from_proto(self._proto.parameters)
 
-    @deprecated(
-        "Use get_parameters() instead. This method will be removed in a future release.",
-    )
-    def get_simulation_param(self) -> SimulationParam:
-        """
-        Returns a copy of the simulation parameters associated with this template.
-        """
-        return self.get_parameters()
-
     def list_tables(
         self,
         table_type: Optional[TableType] = None,
@@ -490,7 +480,7 @@ class SimulationTemplate(ProtoWrapperBase):
         code += "\n\n\n"
         code += '# Create a new simulation template or modify the one that is synced with the UI "Setup" tab.\n'
         code += f'project = luminarycloud.get_project("{self.project_id}")\n'
-        escaped_name = self.name.replace('\\','\\\\').replace('"','\\"')
+        escaped_name = self.name.replace("\\", "\\\\").replace('"', '\\"')
         code += f'template = project.create_simulation_template(name="{escaped_name}")\n'
         code += '# TODO(USER): To modify the "Setup" template, uncomment the line below and comment out the line above.\n'
         code += "# template = project.list_simulation_templates()[0] # Setup template\n\n"

luminarycloud/types/adfloat.py

@@ -1,5 +1,8 @@
+import warnings
 from abc import ABCMeta
-from typing import Any, Union
+from functools import total_ordering
+from typing import Any
+
 from .._proto.base.base_pb2 import AdFloatType, ExpressionType, FirstOrderAdType, SecondOrderAdType
 
 
@@ -9,13 +12,14 @@ class AdFloat(float, metaclass=ABCMeta):
     pass
 
 
+@total_ordering
 class FirstOrderAdFloat(AdFloat):
     """An immutable float with first order adjoints/tangents attached."""
 
     _tangent: tuple[float, ...]
     _adjoint: tuple[float, ...]
 
-    def __new__(cls: type["FirstOrderAdFloat"], value: float, *_: Any) -> "FirstOrderAdFloat":
+    def __new__(cls, value: float, *_: Any) -> "FirstOrderAdFloat":
         return super().__new__(cls, value)
 
     def __init__(self, value: float, tangent: tuple[float, ...], adjoint: tuple[float, ...]):
@@ -45,6 +49,11 @@ class FirstOrderAdFloat(AdFloat):
             and self.adjoint == other.adjoint
         )
 
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, LcFloat):
+            return NotImplemented
+        return _lcfloat_to_float(self) < _lcfloat_to_float(other)
+
     @staticmethod
     def _from_proto(proto: FirstOrderAdType) -> "FirstOrderAdFloat":
         return FirstOrderAdFloat(
@@ -54,6 +63,7 @@ class FirstOrderAdFloat(AdFloat):
         )
 
 
+@total_ordering
 class SecondOrderAdFloat(AdFloat):
     """An immutable float with second order adjoints/tangents attached."""
 
@@ -101,6 +111,11 @@ class SecondOrderAdFloat(AdFloat):
             and self._adjoint == other._adjoint
         )
 
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, LcFloat):
+            return NotImplemented
+        return _lcfloat_to_float(self) < _lcfloat_to_float(other)
+
     @staticmethod
     def _from_proto(proto: SecondOrderAdType) -> "SecondOrderAdFloat":
         return SecondOrderAdFloat(
@@ -110,6 +125,7 @@ class SecondOrderAdFloat(AdFloat):
         )
 
 
+@total_ordering
 class Expression:
     """An expression or value that can be evaluated or used in evaluations."""
 
@@ -119,6 +135,8 @@ class Expression:
     def __init__(self, expression: str):
         if not expression:
             raise ValueError("Expression cannot be empty")
+        # TODO(LC-26796) either evaluate here or in `_to_proto`
+        # (or add a separate method to evaluate, but then `Expression` would no longer be immutable)
         self._value = 0.0
         self._expression = expression
 
@@ -145,11 +163,22 @@ class Expression:
             return False
         return self._value == other._value and self._expression == other._expression
 
-    def _to_code(self, *args) -> str:
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, LcFloat):
+            return NotImplemented
+        return _lcfloat_to_float(self) < _lcfloat_to_float(other)
+
+    def __float__(self) -> float:
+        return self._value
+
+    def __repr__(self) -> str:
+        return self._to_code()
+
+    def _to_code(self, *args: Any) -> str:
         return f"Expression({self._expression.__repr__()})"
 
 
-LcFloat = Union[float, FirstOrderAdFloat, SecondOrderAdFloat, Expression]
+LcFloat = float | FirstOrderAdFloat | SecondOrderAdFloat | Expression
 
 
 def _to_ad_proto(value: LcFloat) -> AdFloatType:
@@ -190,3 +219,18 @@ def _from_ad_proto(proto: AdFloatType) -> LcFloat:
         return 0.0
 
     raise ValueError("Invalid AdFloatType proto")
+
+
+def _lcfloat_to_float(value: LcFloat) -> float:
+    if isinstance(value, AdFloat):
+        return float(value)
+    if isinstance(value, Expression):
+        # TODO(LC-26796) evaluate expressions
+        warnings.warn(
+            "Attempted to convert Expression to float; result may be unexpected. "
+            "This behavior will be improved in a later release.",
+            category=UserWarning,
+            stacklevel=2,
+        )
+        return value.value
+    return value

luminarycloud/types/matrix3.py

@@ -15,9 +15,9 @@ class Matrix3:
 
     def _to_proto(self) -> basepb.Matrix3:
         return basepb.Matrix3(
-            a=basepb.Vector3(x=self.a.x, y=self.a.y, z=self.a.z),
-            b=basepb.Vector3(x=self.b.x, y=self.b.y, z=self.b.z),
-            c=basepb.Vector3(x=self.c.x, y=self.c.y, z=self.c.z),
+            a=self.a._to_base_proto(),
+            b=self.b._to_base_proto(),
+            c=self.c._to_base_proto(),
         )
 
     def _to_ad_proto(self) -> basepb.AdMatrix3:
@@ -28,11 +28,11 @@ class Matrix3:
         )
 
     def _from_proto(self, proto: basepb.Matrix3) -> None:
-        self.a = Vector3(x=proto.a.x, y=proto.a.y, z=proto.a.z)
-        self.b = Vector3(x=proto.b.x, y=proto.b.y, z=proto.b.z)
-        self.c = Vector3(x=proto.c.x, y=proto.c.y, z=proto.c.z)
+        self.a._from_base_proto(proto.a)
+        self.b._from_base_proto(proto.b)
+        self.c._from_base_proto(proto.c)
 
     def _from_ad_proto(self, proto: basepb.AdMatrix3) -> None:
-        self.a = Vector3.from_ad_proto(proto.a)
-        self.b = Vector3.from_ad_proto(proto.b)
-        self.c = Vector3.from_ad_proto(proto.c)
+        self.a._from_ad_proto(proto.a)
+        self.b._from_ad_proto(proto.b)
+        self.c._from_ad_proto(proto.c)

luminarycloud/types/vector3.py

@@ -1,13 +1,15 @@
 # Copyright 2023-2024 Luminary Cloud, Inc. All Rights Reserved.
+from collections.abc import Iterator
 from dataclasses import dataclass
-from typing import TypeAlias, Iterator
+from typing import TypeAlias
+
+from luminarycloud.types import LcFloat
 
 from .._proto.api.v0.luminarycloud.common import common_pb2 as commonpb
-from .._proto.base.base_pb2 import AdVector3, Vector3 as Vector3Proto
-from .adfloat import (
-    _to_ad_proto as _float_to_ad_proto,
-    _from_ad_proto as _float_from_ad_proto,
-)
+from .._proto.base import base_pb2 as basepb
+from .adfloat import Expression, _lcfloat_to_float
+from .adfloat import _from_ad_proto as _float_from_ad_proto
+from .adfloat import _to_ad_proto as _float_to_ad_proto
 
 
 @dataclass
@@ -30,43 +32,64 @@ class Vector3:
         array([1., 2., 3.])
     """
 
-    x: float = 0.0
-    y: float = 0.0
-    z: float = 0.0
+    x: LcFloat = 0.0
+    y: LcFloat = 0.0
+    z: LcFloat = 0.0
 
     def _to_proto(self) -> commonpb.Vector3:
-        return commonpb.Vector3(x=self.x, y=self.y, z=self.z)
+        # TODO(LC-26796) evaluate expressions to do this conversion
+        if any(isinstance(c, Expression) for c in (self.x, self.y, self.z)):
+            raise ValueError(
+                "Cannot convert Vector3 with Expression components to commonpb.Vector3"
+            )
+        return commonpb.Vector3(
+            x=_lcfloat_to_float(self.x),
+            y=_lcfloat_to_float(self.y),
+            z=_lcfloat_to_float(self.z),
+        )
 
     def _from_proto(self, proto: commonpb.Vector3) -> None:
         self.x = proto.x
         self.y = proto.y
         self.z = proto.z
 
-    def _to_ad_proto(self) -> AdVector3:
-        advector = AdVector3()
+    def _to_ad_proto(self) -> basepb.AdVector3:
+        advector = basepb.AdVector3()
         advector.x.CopyFrom(_float_to_ad_proto(self.x))
         advector.y.CopyFrom(_float_to_ad_proto(self.y))
         advector.z.CopyFrom(_float_to_ad_proto(self.z))
         return advector
 
-    def _to_base_proto(self) -> Vector3Proto:
-        return Vector3Proto(x=self.x, y=self.y, z=self.z)
-
-    def _from_ad_proto(self, proto: AdVector3) -> None:
+    def _from_ad_proto(self, proto: basepb.AdVector3) -> None:
         self.x = _float_from_ad_proto(proto.x)
         self.y = _float_from_ad_proto(proto.y)
         self.z = _float_from_ad_proto(proto.z)
 
     @classmethod
-    def from_ad_proto(cls, proto: AdVector3) -> "Vector3":
+    def from_ad_proto(cls, proto: basepb.AdVector3) -> "Vector3":
         vector = cls()
         vector._from_ad_proto(proto)
         return vector
 
-    def __getitem__(self, index: int) -> float:
+    def _to_base_proto(self) -> basepb.Vector3:
+        # TODO(LC-26796) evaluate expressions to do this conversion
+        if any(isinstance(c, Expression) for c in (self.x, self.y, self.z)):
+            raise ValueError("Cannot convert Vector3 with Expression components to basepb.Vector3")
+        return basepb.Vector3(
+            x=_lcfloat_to_float(self.x),
+            y=_lcfloat_to_float(self.y),
+            z=_lcfloat_to_float(self.z),
+        )
+
+    def _from_base_proto(self, proto: basepb.Vector3) -> None:
+        self.x = proto.x
+        self.y = proto.y
+        self.z = proto.z
+
+    def __getitem__(self, index: int) -> LcFloat:
         return [self.x, self.y, self.z][index]
 
-    def __setitem__(self, index: int, value: float) -> None:
+    def __setitem__(self, index: int, value: LcFloat) -> None:
         if index == 0:
             self.x = value
         elif index == 1:
@@ -76,7 +99,7 @@ class Vector3:
         else:
             raise IndexError(f"Index {index} out of bounds for Vector3")
 
-    def __iter__(self) -> Iterator[float]:
+    def __iter__(self) -> Iterator[LcFloat]:
         """Enable iteration over the vector components."""
         yield self.x
         yield self.y
@@ -90,10 +113,12 @@ class Vector3:
 Vector3Like: TypeAlias = Vector3 | list[float] | tuple[float, float, float]  # type: ignore
 
 
-def _to_vector3(value: Vector3Like) -> Vector3:
+def _to_vector3(value: Vector3Like | None) -> Vector3:
+    if value is None:
+        return Vector3()
     if isinstance(value, Vector3):
         return value
-    elif isinstance(value, list) or isinstance(value, tuple):
+    elif isinstance(value, (list, tuple)):
         assert len(value) == 3
         return Vector3(value[0], value[1], value[2])
     else:
@@ -104,5 +129,9 @@ def _to_vector3_proto(value: Vector3Like) -> commonpb.Vector3:
     return _to_vector3(value)._to_proto()
 
 
-def _to_vector3_ad_proto(value: Vector3Like) -> AdVector3:
+def _to_vector3_base_proto(value: Vector3Like) -> basepb.Vector3:
+    return _to_vector3(value)._to_base_proto()
+
+
+def _to_vector3_ad_proto(value: Vector3Like) -> basepb.AdVector3:
     return _to_vector3(value)._to_ad_proto()

luminarycloud/vis/__init__.py

@@ -1,3 +1,4 @@
+from .display import Field as Field
 from .visualization import (
     RenderOutput as RenderOutput,
     Scene as Scene,
@@ -8,6 +9,8 @@ from .visualization import (
     list_cameras as list_cameras,
     RangeResult as RangeResult,
     range_query as range_query,
+    ExtremaResult as ExtremaResult,
+    extrema_query as extrema_query,
     get_camera as get_camera,
     DirectionalCamera as DirectionalCamera,
     LookAtCamera as LookAtCamera,