luminarycloud 0.13.1__py3-none-any.whl → 0.14.1__py3-none-any.whl

luminarycloud/types/adfloat.py

@@ -1,19 +1,40 @@
+from abc import ABCMeta
 from typing import Any
 from .._proto.base.base_pb2 import AdFloatType, FirstOrderAdType, SecondOrderAdType
 
 
-class FirstOrderAdFloat(float):
+class AdFloat(float, metaclass=ABCMeta):
+    """An immutable float with adjoints/tangents"""
+
+    pass
+
+
+class FirstOrderAdFloat(AdFloat):
     """An immutable float with first order adjoints/tangents attached."""
 
-    tangent: tuple[float, ...]
-    adjoint: tuple[float, ...]
+    _tangent: tuple[float, ...]
+    _adjoint: tuple[float, ...]
 
     def __new__(cls: type["FirstOrderAdFloat"], value: float, *_: Any) -> "FirstOrderAdFloat":
         return super().__new__(cls, value)
 
     def __init__(self, value: float, tangent: tuple[float, ...], adjoint: tuple[float, ...]):
-        self.tangent = tuple(float(t) for t in tangent)
-        self.adjoint = tuple(float(a) for a in adjoint)
+        if isinstance(value, AdFloat):
+            raise ValueError("Value cannot be an AdFloat")
+        if any(isinstance(t, AdFloat) for t in tangent):
+            raise ValueError("Tangent cannot be an AdFloat")
+        if any(isinstance(a, AdFloat) for a in adjoint):
+            raise ValueError("Adjoint cannot be an AdFloat")
+        self._tangent = tuple(float(t) for t in tangent)
+        self._adjoint = tuple(float(a) for a in adjoint)
+
+    @property
+    def tangent(self) -> tuple[float, ...]:
+        return self._tangent
+
+    @property
+    def adjoint(self) -> tuple[float, ...]:
+        return self._adjoint
 
     @staticmethod
     def _from_proto(proto: FirstOrderAdType) -> "FirstOrderAdFloat":
@@ -24,12 +45,12 @@ class FirstOrderAdFloat(float):
         )
 
 
-class SecondOrderAdFloat(float):
+class SecondOrderAdFloat(AdFloat):
     """An immutable float with second order adjoints/tangents attached."""
 
-    value: FirstOrderAdFloat
-    tangent: tuple[FirstOrderAdFloat, ...]
-    adjoint: tuple[FirstOrderAdFloat, ...]
+    _value: FirstOrderAdFloat
+    _tangent: tuple[FirstOrderAdFloat, ...]
+    _adjoint: tuple[FirstOrderAdFloat, ...]
 
     def __new__(cls, value: FirstOrderAdFloat, *_: Any) -> "SecondOrderAdFloat":
         return super().__new__(cls, value)
@@ -42,16 +63,25 @@ class SecondOrderAdFloat(float):
     ):
         if not isinstance(value, FirstOrderAdFloat):
             raise TypeError("Value must be a FirstOrderAdFloat")
-        for t in tangent:
-            if not isinstance(t, FirstOrderAdFloat):
-                raise TypeError("Tangent must be a tuple of FirstOrderAdFloat")
-        for a in adjoint:
-            if not isinstance(a, FirstOrderAdFloat):
-                raise TypeError("Adjoint must be a tuple of FirstOrderAdFloat")
-
-        self.value = value
-        self.tangent = tangent
-        self.adjoint = adjoint
+        if any(not isinstance(t, FirstOrderAdFloat) for t in tangent):
+            raise TypeError("Tangent must be a tuple of FirstOrderAdFloat")
+        if any(not isinstance(a, FirstOrderAdFloat) for a in adjoint):
+            raise TypeError("Adjoint must be a tuple of FirstOrderAdFloat")
+        self._value = value
+        self._tangent = tangent
+        self._adjoint = adjoint
+
+    @property
+    def value(self) -> FirstOrderAdFloat:
+        return self._value
+
+    @property
+    def tangent(self) -> tuple[FirstOrderAdFloat, ...]:
+        return self._tangent
+
+    @property
+    def adjoint(self) -> tuple[FirstOrderAdFloat, ...]:
+        return self._adjoint
 
     @staticmethod
     def _from_proto(proto: SecondOrderAdType) -> "SecondOrderAdFloat":

luminarycloud/types/ids.py

@@ -8,3 +8,4 @@ SimulationID = NewType("SimulationID", str)
 SolutionID = NewType("SolutionID", str)
 SimulationTemplateID = NewType("SimulationTemplateID", str)
 GeometryFeatureID = NewType("GeometryFeatureID", str)
+NamedVariableSetID = NewType("NamedVariableSetID", str)

luminarycloud/types/vector3.py

@@ -1,6 +1,6 @@
 # Copyright 2023-2024 Luminary Cloud, Inc. All Rights Reserved.
 from dataclasses import dataclass
-from typing import TypeAlias
+from typing import TypeAlias, Iterator
 
 from .._proto.api.v0.luminarycloud.common import common_pb2 as commonpb
 from .._proto.base.base_pb2 import AdVector3, Vector3 as Vector3Proto
@@ -12,7 +12,23 @@ from .adfloat import (
 
 @dataclass
 class Vector3:
-    """Represents a 3-dimensional vector."""
+    """Represents a 3-dimensional vector.
+
+    Supports direct component access, indexing, iteration, and conversion to numpy arrays.
+
+    Examples:
+        >>> from luminarycloud.types import Vector3
+        >>> v = Vector3(1.0, 2.0, 3.0)
+        >>> v.x, v.y, v.z  # Direct component access
+        (1.0, 2.0, 3.0)
+        >>> v[0]  # Access by index
+        1.0
+        >>> list(v)  # Iterate over components
+        [1.0, 2.0, 3.0]
+        >>> import numpy as np
+        >>> np.array(v)  # Convert to numpy array
+        array([1., 2., 3.])
+    """
 
     x: float = 0.0
     y: float = 0.0
@@ -60,6 +76,16 @@ class Vector3:
         else:
             raise IndexError(f"Index {index} out of bounds for Vector3")
 
+    def __iter__(self) -> Iterator[float]:
+        """Enable iteration over the vector components."""
+        yield self.x
+        yield self.y
+        yield self.z
+
+    def __len__(self) -> int:
+        """Return the number of components in the vector."""
+        return 3
+
 
 Vector3Like: TypeAlias = Vector3 | list[float] | tuple[float, float, float]  # type: ignore
 

luminarycloud/vis/__init__.py

@@ -1,5 +1,5 @@
 from .visualization import (
-    RenderOutput as RenderOuptut,
+    RenderOutput as RenderOutput,
     Scene as Scene,
     ColorMapPreset as ColorMapPreset,
     EntityType as EntityType,
@@ -19,6 +19,7 @@ from .filters import (
     ScaledVectorGlyphs as ScaledVectorGlyphs,
     RakeStreamlines as RakeStreamlines,
     SurfaceStreamlines as SurfaceStreamlines,
+    SurfaceLIC as SurfaceLIC,
     Threshold as Threshold,
     Isosurface as Isosurface,
 )

luminarycloud/vis/display.py

@@ -11,19 +11,17 @@ class Field:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attribues:
-    ----------
-    quantity : VisQuantity
-        The quantity to color by.
-    component : FieldComponent
-        The component of the field to use, applicable to vector fields. If the field is a
-        scalar, use the default X component.
     """
 
     quantity: VisQuantity = VisQuantity.ABSOLUTE_PRESSURE
+    """The quantity to color by."""
     component: FieldComponent = FieldComponent.X
+    """
+    The component of the field to use, applicable to vector fields. If the field is a
+    scalar, use the default X component.
+    """
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash((self.quantity, self.component))
 
 
@@ -35,25 +33,23 @@ class DisplayAttributes:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    ----------
-    visible : bool
-        If the object is visible or not. Default: True
-    opacity : float
-        How opaque the object is. This is a normalized number between
-        0 (i.e., fully transparent) and 1 (i.e., fully opaque). Default: 1
-    field : Field
-        What field quantity/component to color by, if applicable.
-    representation : Representation
-        how the object is represented in the scene (e.g., surface, surface with
-        edges, wireframe or points). Default: surface.
     """
 
     visible: bool = True
+    """If the object is visible or not. Default: True"""
     # TODO(matt): opacity not hooked up yet.
     opacity: float = 1.0
+    """
+    How opaque the object is. This is a normalized number between
+    0 (i.e., fully transparent) and 1 (i.e., fully opaque). Default: 1
+    """
     field: Field = dc.field(default_factory=Field)
+    """What field quantity/component to color by, if applicable."""
     representation: Representation = Representation.SURFACE
+    """
+    how the object is represented in the scene (e.g., surface, surface with
+    edges, wireframe or points). Default: surface.
+    """
 
     def _to_proto(self) -> vis_pb2.DisplayAttributes:
         attrs = vis_pb2.DisplayAttributes()
@@ -73,16 +69,12 @@ class DataRange:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    min_value : float
-        The minimum value of the range.
-    max_value : float
-        The maximum value of the range.
     """
 
     min_value: float = float("inf")
+    """The minimum value of the range."""
     max_value: float = float("-inf")
+    """The maximum value of the range."""
 
     def is_valid(self) -> bool:
         return self.max_value >= self.min_value
@@ -101,30 +93,26 @@ class ColorMapAppearance:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes
-    ----------
-    visible: bool
-        Controls if the color map is displayed or not. Default: True
-    width: float
-        The width of the color map in normalized device coordinates. Default: 0.034
-    height: float
-        The height of the color map in normalized device coordinates. Default: 0.146
-    text_size: int
-        The text size for the color map legend in pixels. Default: 36
-    lower_left_x: float
-        The lower left x position of the color map in normalized device
-        coordinates. Default: 0.8
-    lower_left_y: float
-        The lower left y position of the color map in normalized device
-        coordinates. Default: 0.8
     """
 
     visible: bool = True
+    """Controls if the color map is displayed or not. Default: True"""
     width: float = 0.034
+    """The width of the color map in normalized device coordinates. Default: 0.034"""
     height: float = 0.146
+    """The height of the color map in normalized device coordinates. Default: 0.146"""
     text_size: int = 36
+    """The text size for the color map legend in pixels. Default: 36"""
     lower_left_x: float = 0.8
+    """
+    The lower left x position of the color map in normalized device
+    coordinates. Default: 0.8
+    """
     lower_left_y: float = 0.8
+    """
+    The lower left y position of the color map in normalized device
+    coordinates. Default: 0.8
+    """
 
 
 @dc.dataclass
@@ -140,39 +128,41 @@ class ColorMap:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes
-    ----------
-    field : Field
-        The field and component this color map applies to.
-    preset : ColorMapPreset
-        The color map preset to use. This defines the colors used in the color
-        map. Default is 'JET'.
-    data_range : DataRange
-        An optional data range to use for the color map. The user must explicity
-        set the data ranges. If not set explicitly, the fields global data range
-        is used. For comparing multiple results, either with different solutions
-        in the same simulation or with different simulations, its highly
-        recommended that a range is provided so the color scales are the same
-        between the resulting images. Default: is an invalid data range.
-    discretize : bool
-        Use discrete color bins instead of a continuous range. When True,
-        'n_colors' indicates how many discrete bins to use. Default: False.
-    n_colors : int
-        How many discrete bins to use when discretize is True. Valid n_colors
-        values are [1, 256]. Default: 8.
-    appearance: Optional[ColorMapAppearance]
-        This attribute controls how the color map annotation appears in the image, including
-        location, size, and visibility. When the scene is set to automatic color maps, these
-        attributes are automatically populated unless overridden. When setting the appearance,
-        the user is responsible for setting all values.
     """
 
     field: Field = dc.field(default_factory=Field)
+    """The field and component this color map applies to."""
     preset: ColorMapPreset = ColorMapPreset.JET
+    """
+    The color map preset to use. This defines the colors used in the color
+    map. Default is 'JET'.
+    """
     data_range: DataRange = dc.field(default_factory=DataRange)
+    """
+    An optional data range to use for the color map. The user must explicity
+    set the data ranges. If not set explicitly, the fields global data range
+    is used. For comparing multiple results, either with different solutions
+    in the same simulation or with different simulations, its highly
+    recommended that a range is provided so the color scales are the same
+    between the resulting images. Default: is an invalid data range.
+    """
     discretize: bool = False
+    """
+    Use discrete color bins instead of a continuous range. When True,
+    'n_colors' indicates how many discrete bins to use. Default: False.
+    """
     n_colors: int = 8
+    """
+    How many discrete bins to use when discretize is True. Valid n_colors
+    values are [1, 256]. Default: 8.
+    """
     appearance: Optional[ColorMapAppearance] = None
+    """
+    This attribute controls how the color map annotation appears in the image, including
+    location, size, and visibility. When the scene is set to automatic color maps, these
+    attributes are automatically populated unless overridden. When setting the appearance,
+    the user is responsible for setting all values.
+    """
 
     def _to_proto(self) -> vis_pb2.ColorMap:
         res: vis_pb2.ColorMap = vis_pb2.ColorMap()

luminarycloud/vis/filters.py

@@ -21,38 +21,32 @@ class Plane:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    origin : Vector3
-        A point defined on the plane. Default: [0,0,0].
-    normal : Vector3
-        The vector orthogonal to the  plane. Default: [0,1,0]
     """
 
     origin: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """A point defined on the plane. Default: [0,0,0]."""
     normal: Vector3Like = dc.field(default_factory=lambda: Vector3(x=1, y=0, z=0))
+    """The vector orthogonal to the  plane. Default: [0,1,0]"""
 
 
 @dc.dataclass
 class Box:
     """
     This class defines a box used for filter such as box clip.
+
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    center: Vector3
-        A point defined at the center of the box. Default: [0,0,0].
-    lengths: Vector3
-        The the legnths of each side of the box. Default: [1,1,1]
-    angles: Vector3
-        The rotation of the box specified in Euler angles (degrees) and applied
-        in XYZ ordering. Default: [0,0,0]
     """
 
     center: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """A point defined at the center of the box. Default: [0,0,0]."""
     lengths: Vector3Like = dc.field(default_factory=lambda: Vector3(x=1, y=1, z=1))
+    """The the legnths of each side of the box. Default: [1,1,1]"""
     angles: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """
+    The rotation of the box specified in Euler angles (degrees) and applied
+    in XYZ ordering. Default: [0,0,0]
+    """
 
 
 class Filter(ABC):
@@ -201,7 +195,7 @@ class Isosurface(Filter):
         if len(self.isovalues) == 0:
             raise ValueError("Isosurface: isovalue must be non-empty")
 
-        if self.field == VisQuantity.NONE:
+        if self.field.quantity == VisQuantity.NONE:
             raise ValueError("Isosurface: field can't be None")
 
         vis_filter = vis_pb2.Filter()
@@ -654,6 +648,8 @@ class SurfaceStreamlines(Streamlines):
         id: str
             A surface id or a tag id.
         """
+        if not isinstance(id, str):
+            raise TypeError(f"Expected 'str', got {type(id).__name__}")
         self._surface_names.append(id)
 
     def _surfaces(self) -> List[str]:
@@ -700,3 +696,88 @@ class SurfaceStreamlines(Streamlines):
             vis_filter.streamlines.surface.surface_names.append(id)
         vis_filter.streamlines.field.quantity_typ = self.field.quantity.value
         return vis_filter
+
+
+class SurfaceLIC(Filter):
+    """
+    A Surface Line Integral Convolution (LIC) filter is used to depict the flow
+    direction and structure of vector fields (such as velocity) on surfaces. It
+    enhances the perception of complex flow patterns by convolving noise
+    textures along streamlines, making it easier to visually interpret the
+    behavior of fluid flow on boundaries or surfaces in a simulation.
+
+    The input is a list of surfaces. If none are specified, all are used. The
+    surface LIC outputs grey scale colors on the specified surfaces. When the
+    display attributes quantity is not None, the field colors are blended with
+    the grey scale colors.
+
+    Note: surface LIC computes on the same surfaces of the solution. If the surfaces in
+    the global display attributes are not hidden, the surface LIC will not be visible since
+    the existing surfaces are occluding it.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+
+    Attributes:
+    -----------
+    field: Field
+        Specifies the field used to advect particles for the surface LIC.
+        Default: WALL_SHEER_STRESS
+    contrast: float
+        Contrast controls the contrast of the resuting surface LIC. Valid values
+        are in the [0.2, 3.0] range. Lower values means less contrast and
+        higher values mean more contrast. Default: 1
+    """
+
+    def __init__(self, name: str) -> None:
+        super().__init__(generate_id("surface-lic-"))
+        self.name = name
+        self.contrast: float = 1.0
+        self._surface_names: List[str] = []
+        self.field: Field = Field()
+        self.field.quantity = VisQuantity.WALL_SHEAR_STRESS
+
+    def add_surface(self, id: str) -> None:
+        """
+        Add a surface to generate compute the surface LIC on. Adding no
+        surfaces indicates that all surfaces will be used.
+
+        Parameters
+        ----------
+        id: str
+            A surface id or a tag id.
+        """
+        if not isinstance(id, str):
+            raise TypeError(f"Expected 'str', got {type(id).__name__}")
+        self._surface_names.append(id)
+
+    def _surfaces(self) -> List[str]:
+        """
+        Returns the current list of surfaces.
+        """
+        return self._surface_names
+
+    def _to_proto(self) -> vis_pb2.Filter:
+        vis_filter = vis_pb2.Filter()
+        vis_filter.id = self.id
+        vis_filter.name = self.name
+        # Prevent common mistakes that cause confusion. The only current option
+        # is to be on a surface, so no velocity.
+        if not isinstance(self.field, Field):
+            raise TypeError(f"Expected 'Field', got {type(self.field).__name__}")
+        if self.field.quantity == VisQuantity.VELOCITY:
+            raise ValueError("SurfaceLIC: velocity is 0 on surfaces and will produce no data")
+        if not isinstance(self.contrast, (int, float)):
+            raise TypeError(f"Expected 'int or float', got {type(self.contrast).__name__}")
+        if self.contrast < 0.2 or self.contrast > 3.0:
+            raise ValueError("SurfaceLIC: contrast must be between 0.2 and 3.0")
+
+        for id in self._surface_names:
+            vis_filter.surface_lic.geometry.surface_names.append(id)
+        if len(self._surface_names) == 0:
+            # we need to make sure that the geometry is populated.
+            geometry = vis_pb2.SurfaceLICGeomtery()
+            vis_filter.surface_lic.geometry.CopyFrom(geometry)
+
+        vis_filter.surface_lic.field.quantity_typ = self.field.quantity.value
+        vis_filter.surface_lic.contrast = self.contrast
+        return vis_filter

luminarycloud/vis/interactive_scene.py

@@ -1,7 +1,7 @@
 from .display import DisplayAttributes
 from .filters import SurfaceStreamlines, Filter
 from .._client import get_default_client
-from ..enum.vis_enums import EntityType
+from ..enum.vis_enums import EntityType, SceneMode
 from typing import TYPE_CHECKING, cast
 
 from .._proto.api.v0.luminarycloud.vis import vis_pb2
@@ -15,6 +15,9 @@ except ImportError:
     lcj = None
 
 
+_SOURCE_FILTER_ID = "___LC_SOURCE_FILTER___"
+
+
 class InteractiveScene:
     """
     The InteractiveScene acts as the bridge between the the Scene and
@@ -25,10 +28,10 @@ class InteractiveScene:
 
     # Using the type causes a circular import error, not sure on best way to resolve.
     # I do want to keep this in a separate file
-    def __init__(self, scene: "Scene") -> None:
+    def __init__(self, scene: "Scene", mode: SceneMode) -> None:
         if not lcj:
             raise ImportError("InteractiveScene requires luminarycloud[jupyter] to be installed")
-        self.widget = lcj.LCVisWidget()
+        self.widget = lcj.LCVisWidget(scene_mode=mode)
         self.set_scene(scene)
 
     def _ipython_display_(self) -> None:
@@ -39,6 +42,9 @@ class InteractiveScene:
         self.widget._ipython_display_()
 
     def set_scene(self, scene: "Scene") -> None:
+        # Import here to avoid circular import issue
+        from .visualization import LookAtCamera
+
         # Display the initial scene we've been given
         # Submit request for the render data URLs we need
         req = vis_pb2.GetRenderDataUrlsRequest()
@@ -85,6 +91,27 @@ class InteractiveScene:
         # is moved there.
         self.widget.set_workspace_state(scene, resp)
 
+        # Sync display attributes and visibilities for surfaces
+        self.set_display_attributes(_SOURCE_FILTER_ID, scene.global_display_attrs)
+        for s, v in scene._surface_visibilities.items():
+            self.set_surface_visibility(s, v)
+
+        for f in scene._filters:
+            self.set_display_attributes(f.id, f.display_attrs)
+
+        # Find and apply the first look at camera, if any, in the scene
+        set_camera = False
+        for c in scene._cameras:
+            if not isinstance(c, LookAtCamera):
+                continue
+            set_camera = True
+            self.set_camera(c)
+
+        # If we don't have an initial camera to use, reset the camera after loading
+        # the workspace state
+        if not set_camera:
+            self.reset_camera()
+
     def set_surface_visibility(self, surface_id: str, visible: bool) -> None:
         self.widget.set_surface_visibility(surface_id, visible)
 
@@ -97,6 +124,13 @@ class InteractiveScene:
     def reset_camera(self) -> None:
         self.widget.reset_camera()
 
+    def set_camera(self, camera: "LookAtCamera") -> None:
+        # Clear the camera pan, we should add this to the SDK later
+        self.widget.camera_pan = [0, 0]
+        self.widget.camera_position = [camera.position[0], camera.position[1], camera.position[2]]
+        self.widget.camera_look_at = [camera.look_at[0], camera.look_at[1], camera.look_at[2]]
+        self.widget.camera_up = [camera.up[0], camera.up[1], camera.up[2]]
+
     def get_camera(self) -> "LookAtCamera":
         # Import here to avoid circular import issue
         from .visualization import LookAtCamera
@@ -106,3 +140,6 @@ class InteractiveScene:
         camera.look_at = self.widget.camera_look_at
         camera.up = self.widget.camera_up
         return camera
+
+    def set_triad_visible(self, visible: bool) -> None:
+        self.widget.set_triad_visible(visible)