luminarycloud 0.15.1__py3-none-any.whl → 0.15.3__py3-none-any.whl

luminarycloud/meshing/mesh_generation_params.py

@@ -16,10 +16,11 @@ from ..params.geometry import (
 )
 from ..types import Vector3
 from .sizing_strategy import MaxCount, Minimal, MinimalCount, SizingStrategy, TargetCount
+from ..pipeline_util.dictable import PipelineDictable
 
 
 @dataclass(kw_only=True)
-class VolumeMeshingParams:
+class VolumeMeshingParams(PipelineDictable):
     """Volume meshing parameters."""
 
     volumes: list[Volume]
@@ -38,7 +39,7 @@ class VolumeMeshingParams:
 
 
 @dataclass(kw_only=True)
-class ModelMeshingParams:
+class ModelMeshingParams(PipelineDictable):
     """Model meshing parameters."""
 
     surfaces: Sequence[Surface | str]
@@ -61,7 +62,7 @@ class ModelMeshingParams:
 
 
 @dataclass(kw_only=True)
-class BoundaryLayerParams:
+class BoundaryLayerParams(PipelineDictable):
     """Boundary layer meshing parameters."""
 
     surfaces: Sequence[Surface | str]
@@ -87,7 +88,7 @@ class BoundaryLayerParams:
 
 
 @dataclass(kw_only=True)
-class RefinementRegion:
+class RefinementRegion(PipelineDictable):
     """Refinement region parameters."""
 
     name: str
@@ -137,7 +138,7 @@ class RefinementRegion:
 
 
 @dataclass(kw_only=True)
-class MeshGenerationParams:
+class MeshGenerationParams(PipelineDictable):
     """Mesh generation parameters."""
 
     geometry_id: str

luminarycloud/meshing/sizing_strategy/sizing_strategies.py

@@ -1,10 +1,11 @@
 from dataclasses import dataclass
 
 from luminarycloud._helpers.warnings.deprecated import deprecated
+from ...pipeline_util.dictable import PipelineDictable
 
 
 @dataclass
-class SizingStrategy:
+class SizingStrategy(PipelineDictable):
     """Sizing strategy parameters."""
 
     pass

luminarycloud/named_variable_set.py

@@ -32,6 +32,8 @@ class NamedVariableSet(ProtoWrapperBase):
         Time the named variable set was created.
     update_time : datetime
         Time the named variable set was last updated.
+    version_id : str
+        ID of the current (latest) version of the named variable set.
 
     Examples
     --------
@@ -45,7 +47,7 @@ class NamedVariableSet(ProtoWrapperBase):
     id: NamedVariableSetID
     "Named variable set ID."
     project_id: ProjectID
-    "ID of the project containing this simulation."
+    "ID of the project containing this named variable set."
 
     _proto: namedvariablepb.NamedVariableSet
     _named_variables: dict[str, float | str] | None

luminarycloud/physics_ai/inference.py

@@ -0,0 +1,55 @@
+# File: python/sdk/luminarycloud/inference/inference.py
+# Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from json import loads as json_loads
+
+from .._client import get_default_client
+from .._helpers._timestamp_to_datetime import timestamp_to_datetime
+from .._proto.api.v0.luminarycloud.inference import inference_pb2 as inferencepb
+from .._proto.inferenceservice import inferenceservice_pb2 as inferenceservicepb
+from .._wrapper import ProtoWrapper, ProtoWrapperBase
+from .._helpers.warnings import experimental
+
+
+@experimental
+def start_inference_job(
+    stl_url: str,
+    model_url: str,
+    config_name: str,
+    stencil_size: int,
+) -> dict[str, Any]:
+    """Creates an inference service job.
+    Parameters
+    ----------
+    stl_url : str
+        URL of the STL file to be used for inference.
+    model_url : str
+        URL of the model to be used for inference.
+    config_name :str
+        Name of the configuration to be used for inference.
+    stencil_size :int
+        Size of the stencil to be used for inference.
+
+
+    Returns
+    dict[str, Any]
+        Response from the server as key-value pairs.
+
+    warning:: This feature is experimental and may change or be removed without notice.
+    """
+
+    req = inferencepb.CreateInferenceServiceJobRequest(
+        stl_url=stl_url,
+        model_url=model_url,
+        config_name=config_name,
+        stencil_size=stencil_size,
+    )
+
+    res: inferencepb.CreateInferenceServiceJobResponse = (
+        get_default_client().CreateInferenceServiceJob(req)
+    )
+
+    return json_loads(str(res.response, encoding="utf-8"))

luminarycloud/pipeline_util/dictable.py

@@ -0,0 +1,27 @@
+from dataclasses import fields, is_dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from luminarycloud.pipelines.parameters import PipelineParameter
+
+
+class PipelineDictable:
+    """
+    A mixin for dataclasses that can contain PipelineParameters and/or other PipelineDictables
+    (i.e. it's recursive). Used to construct a dictionary that can be serialized to YAML for a
+    Pipeline definition, and collects all PipelineParameters encountered along the way.
+    """
+
+    def _to_pipeline_dict(self) -> tuple[dict, list["PipelineParameter"]]:
+        if not is_dataclass(self):
+            raise ValueError("PipelineDictable can only be used on dataclasses")
+        result = {}
+        params = []
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if hasattr(value, "_to_pipeline_dict"):
+                result[field.name], downstream_params = value._to_pipeline_dict()
+                params.extend(downstream_params)
+            else:
+                result[field.name] = value
+        return result, params

luminarycloud/pipeline_util/yaml.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+from typing import Any
+import yaml
+
+
+@dataclass
+class YamlProblem:
+    path: str
+    problem: str
+
+    def __str__(self) -> str:
+        return f"{self.path}: {self.problem}"
+
+
+def find_yaml_problems(
+    data: Any, path: str = "", problems: list[YamlProblem] | None = None
+) -> list[YamlProblem]:
+    """
+    Find any problems with the given data that would prevent it from being serialized to "standard"
+    YAML, i.e. it's all dicts, lists, and primitives.
+
+    Returns a list of YamlProblem instances, which will be empty if there are no problems.
+    """
+    if problems is None:
+        problems = []
+    if isinstance(data, (str, int, float, bool, type(None))):
+        return problems
+    elif isinstance(data, list):
+        for i, item in enumerate(data):
+            find_yaml_problems(item, f"{path}[{i}]", problems)
+    elif isinstance(data, dict):
+        for k, v in data.items():
+            if not isinstance(k, str):
+                problems.append(YamlProblem(path, f"Invalid dict key: {type(k).__name__}"))
+                return problems
+            find_yaml_problems(v, f"{path}.{k}", problems)
+    else:
+        problems.append(YamlProblem(path, f"Invalid type: {type(data).__name__}"))
+    return problems
+
+
+def ensure_yamlizable(data: Any, data_description: str) -> None:
+    """
+    Ensure that the given data is serializable to YAML without any non-standard tags. I.e. it's all
+    dicts, lists, and primitives.
+
+    Raises a TypeError with a very descriptive error message if the data is not serializable.
+    """
+    problems = find_yaml_problems(data)
+    if problems:
+        bad_yaml = yaml.dump(data)
+        problems_str = " - " + "\n - ".join(str(p) for p in problems)
+        raise TypeError(
+            f"Failed to serialize {data_description} to safe YAML:\n\n{bad_yaml}\nProblems:\n{problems_str}"
+        )

luminarycloud/pipelines/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
+from .core import (
+    Pipeline as Pipeline,
+)
+
+from .parameters import (
+    StringPipelineParameter as StringPipelineParameter,
+    IntPipelineParameter as IntPipelineParameter,
+    FloatPipelineParameter as FloatPipelineParameter,
+    BoolPipelineParameter as BoolPipelineParameter,
+)
+
+from .operators import (
+    # Operator base class, mainly exported for testing
+    Operator as Operator,
+    # PipelineOutputs, i.e. things that "flow" in a Pipeline
+    PipelineOutputGeometry as PipelineOutputGeometry,
+    PipelineOutputMesh as PipelineOutputMesh,
+    PipelineOutputSimulation as PipelineOutputSimulation,
+    # Concrete operators and their output types
+    ReadGeometry as ReadGeometry,
+    ReadGeometryOutputs as ReadGeometryOutputs,
+    ModifyGeometry as ModifyGeometry,
+    ModifyGeometryOutputs as ModifyGeometryOutputs,
+    Mesh as Mesh,
+    MeshOutputs as MeshOutputs,
+    Simulate as Simulate,
+    SimulateOutputs as SimulateOutputs,
+)

luminarycloud/pipelines/core.py

@@ -0,0 +1,225 @@
+# Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
+from abc import ABC, abstractmethod
+from dataclasses import is_dataclass, fields
+from typing import Type, TypeVar, Generic
+import re
+import yaml
+
+from .._helpers.warnings import experimental
+from ..pipeline_util.yaml import ensure_yamlizable
+
+
+class PipelineParameter(ABC):
+    """
+    Base class for all concrete PipelineParameters.
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+        self._validate()
+
+    @property
+    def type(self) -> str:
+        return self._type()
+
+    @abstractmethod
+    def _type(self) -> str:
+        pass
+
+    def _validate(self) -> None:
+        if not re.match(r"^[a-zA-Z0-9_-]+$", self.name):
+            raise ValueError(
+                "name must only contain alphanumeric characters, underscores and hyphens"
+            )
+
+    def _add_to_params(self, params: dict) -> None:
+        if self.name in params and params[self.name]["type"] != self.type:
+            raise ValueError(
+                f"Parameter name {self.name} used with multiple types: {params[self.name]['type']} != {self.type}"
+            )
+        params[self.name] = {"type": self.type}
+
+    def _to_pipeline_dict(self) -> tuple[dict, list["PipelineParameter"]]:
+        return {"$pipeline_param": self.name}, [self]
+
+
+class PipelineInput:
+    """
+    A named input for an Operator instance (i.e. a Task). Explicitly connected to a PipelineOutput.
+    """
+
+    def __init__(self, upstream_output: "PipelineOutput", owner: "Operator", name: str):
+        self.upstream_output = upstream_output
+        self.owner = owner
+        self.name = name
+
+    def _to_dict(self, id_for_task: dict) -> dict:
+        if self.upstream_output.owner not in id_for_task:
+            raise ValueError(
+                f"Task {self.owner} depends on a task, {self.upstream_output.owner}, that isn't in the Pipeline. Did you forget to add it?"
+            )
+        upstream_task_id = id_for_task[self.upstream_output.owner]
+        upstream_output_name = self.upstream_output.name
+        return {self.name: f"{upstream_task_id}.{upstream_output_name}"}
+
+
+class PipelineOutput(ABC):
+    """
+    A named output for an Operator instance (i.e. a Task). Can be used to spawn any number of
+    connected PipelineInputs.
+    """
+
+    def __init__(self, owner: "Operator", name: str):
+        self.owner = owner
+        self.name = name
+        self.downstream_inputs: list[PipelineInput] = []
+
+    def _spawn_input(self, owner: "Operator", name: str) -> PipelineInput:
+        input = PipelineInput(self, owner, name)
+        self.downstream_inputs.append(input)
+        return input
+
+
+class OperatorInputs:
+    """
+    A collection of all PipelineInputs for an Operator instance (i.e. a Task).
+    """
+
+    def __init__(
+        self, owner: "Operator", **input_descriptors: tuple[Type[PipelineOutput], PipelineOutput]
+    ):
+        """
+        input_descriptors is a dict of input name -> (required_upstream_output_type, upstream_output)
+        We have that required_upstream_output_type so we can do runtime validation that each given
+        output is of the correct type for the input it's hooked up to.
+        """
+        self.inputs: set[PipelineInput] = set()
+        for name, (required_upstream_output_type, upstream_output) in input_descriptors.items():
+            if not isinstance(upstream_output, required_upstream_output_type):
+                raise ValueError(
+                    f"Input {name} must be a {required_upstream_output_type.__name__}, got {upstream_output.__class__.__name__}"
+                )
+            self.inputs.add(upstream_output._spawn_input(owner, name))
+
+    def _to_dict(self, id_for_task: dict) -> dict[str, str]:
+        d: dict[str, str] = {}
+        for input in self.inputs:
+            d |= input._to_dict(id_for_task)
+        return d
+
+
+T = TypeVar("T", bound="OperatorOutputs")
+
+
+class OperatorOutputs(ABC):
+    """
+    A collection of all PipelineOutputs for an Operator instance (i.e. a Task). Must be subclassed,
+    and the subclass must also be a dataclass whose fields are all PipelineOutput subclasses. Then
+    that subclass should be instantiated with `_instantiate_for`. Sounds a little complicated,
+    perhaps, but it's not bad. See the existing subclasses in `./operators.py` for examples.
+    """
+
+    @classmethod
+    def _instantiate_for(cls: type[T], owner: "Operator") -> T:
+        # create an instance with all fields instantiated with the given owner, and named by the
+        # field name.
+        # Also validate here that we are a dataclass, and all our fields are PipelineOutput types.
+        # Would love to get this done in the type system, but I think it's impossible, so this is
+        # the next best thing.
+        if not is_dataclass(cls):
+            raise TypeError(f"'{cls.__name__}' must be a dataclass")
+        outputs = {}
+        for field in fields(cls):
+            assert not isinstance(field.type, str)
+            if not issubclass(field.type, PipelineOutput):
+                raise TypeError(
+                    f"Field '{field.name}' in '{cls.__name__}' must be a subclass of PipelineOutput"
+                )
+            outputs[field.name] = field.type(owner, field.name)
+        return cls(**outputs)
+
+
+TOutputs = TypeVar("TOutputs", bound=OperatorOutputs)
+
+
+class Operator(Generic[TOutputs], ABC):
+    def __init__(
+        self,
+        task_name: str | None,
+        params: dict,
+        inputs: OperatorInputs,
+        outputs: TOutputs,
+    ):
+        self._operator_name = self.__class__.__name__
+        self._task_name = task_name if task_name is not None else self._operator_name
+        self._params = params
+        self._inputs = inputs
+        self.outputs = outputs
+        ensure_yamlizable(self._params_dict()[0], "Operator parameters")
+
+    def _to_dict(self, id_for_task: dict) -> tuple[dict, list[PipelineParameter]]:
+        params, params_list = self._params_dict()
+        d = {
+            "name": self._task_name,
+            "operator": self._operator_name,
+            "params": params,
+            "inputs": self._inputs._to_dict(id_for_task),
+        }
+        return d, params_list
+
+    def _params_dict(self) -> tuple[dict, list[PipelineParameter]]:
+        d = {}
+        params = []
+        for name, value in self._params.items():
+            if hasattr(value, "_to_pipeline_dict"):
+                d[name], downstream_params = value._to_pipeline_dict()
+                params.extend(downstream_params)
+            else:
+                d[name] = value
+        return d, params
+
+    def __str__(self) -> str:
+        return f'{self._operator_name}(name="{self._task_name}")'
+
+
+@experimental
+class Pipeline:
+    def __init__(self, name: str, tasks: list[Operator]):
+        self.name = name
+        self.tasks = tasks
+
+    def to_yaml(self) -> str:
+        return yaml.safe_dump(self._to_dict())
+
+    def _to_dict(self) -> dict:
+        id_for_task = self._assign_ids_to_tasks()
+        tasks = {}
+        params = []
+        for task in id_for_task.keys():
+            task_dict, referenced_params = task._to_dict(id_for_task)
+            tasks[id_for_task[task]] = task_dict
+            params.extend(referenced_params)
+
+        d = {
+            "lc_pipeline": {
+                "schema_version": 1,
+                "name": self.name,
+                "params": self._pipeline_params_dict(params),
+                "tasks": tasks,
+            }
+        }
+        ensure_yamlizable(d, "Pipeline")
+        return d
+
+    def _assign_ids_to_tasks(self) -> dict[Operator, str]:
+        return {task: f"t{i + 1}-{task._operator_name}" for i, task in enumerate(self.tasks)}
+
+    def _pipeline_params_dict(self, params: list[PipelineParameter]) -> dict:
+        d: dict[str, dict] = {}
+        for p in params:
+            if p.name in d and d[p.name]["type"] != p.type:
+                raise ValueError(
+                    f'PipelineParameter "{p.name}" used with multiple types: {d[p.name]["type"]} != {p.type}'
+                )
+            d[p.name] = {"type": p.type}
+        return d

luminarycloud/pipelines/operators.py

@@ -0,0 +1,197 @@
+# Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
+from dataclasses import dataclass
+
+from .._helpers.warnings import experimental
+from .core import Operator, OperatorInputs, OperatorOutputs, PipelineOutput
+from .parameters import StringPipelineParameter
+from ..meshing import MeshGenerationParams
+
+
+# Concrete PipelineOutput classes, i.e. the things that can "flow" in a Pipeline
+
+
+class PipelineOutputGeometry(PipelineOutput):
+    """A representation of a Geometry in a Pipeline."""
+
+    pass
+
+
+class PipelineOutputMesh(PipelineOutput):
+    """A representation of a Mesh in a Pipeline."""
+
+    pass
+
+
+class PipelineOutputSimulation(PipelineOutput):
+    """A representation of a Simulation in a Pipeline."""
+
+    pass
+
+
+# Operators
+
+
+@dataclass
+class ReadGeometryOutputs(OperatorOutputs):
+    geometry: PipelineOutputGeometry
+    """
+    The Geometry identified by the given `geometry_id`, in the state it was in when the Pipeline was
+    invoked. I.e. the latest GeometryVersion at that moment.
+    """
+
+
+@experimental
+class ReadGeometry(Operator[ReadGeometryOutputs]):
+    """
+    Reads a Geometry into the Pipeline.
+
+    Parameters
+    ----------
+    geometry_id : str | StringPipelineParameter
+        The ID of the Geometry to retrieve.
+
+    Outputs
+    -------
+    geometry : PipelineOutputGeometry
+        The latest GeometryVersion of the Geometry as of the moment the Pipeline was invoked.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+    """
+
+    def __init__(
+        self,
+        *,
+        task_name: str | None = None,
+        geometry_id: str | StringPipelineParameter,
+    ):
+        super().__init__(
+            task_name,
+            {"geometry_id": geometry_id},
+            OperatorInputs(self),
+            ReadGeometryOutputs._instantiate_for(self),
+        )
+
+
+@dataclass
+class ModifyGeometryOutputs(OperatorOutputs):
+    geometry: PipelineOutputGeometry
+    """The modified Geometry, represented as a new GeometryVersion."""
+
+
+# TODO: figure out what `mods` actually is. What does the non-pipeline geo mod interface look like?
+@experimental
+class ModifyGeometry(Operator[ModifyGeometryOutputs]):
+    """
+    Modifies a Geometry.
+
+    Parameters
+    ----------
+    mods : dict
+        The modifications to apply to the Geometry.
+    geometry : PipelineOutputGeometry
+        The Geometry to modify.
+
+    Outputs
+    -------
+    geometry : PipelineOutputGeometry
+        The modified Geometry, represented as a new GeometryVersion.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+    """
+
+    def __init__(
+        self,
+        *,
+        task_name: str | None = None,
+        mods: list[dict],
+        geometry: PipelineOutputGeometry,
+    ):
+        raise NotImplementedError("ModifyGeometry is not implemented yet.")
+        super().__init__(
+            task_name,
+            {"mods": mods},
+            OperatorInputs(self, geometry=(PipelineOutputGeometry, geometry)),
+            ModifyGeometryOutputs._instantiate_for(self),
+        )
+
+
+@dataclass
+class MeshOutputs(OperatorOutputs):
+    mesh: PipelineOutputMesh
+    """The Mesh generated from the given Geometry."""
+
+
+@experimental
+class Mesh(Operator[MeshOutputs]):
+    """
+    Generates a Mesh from a Geometry.
+
+    Parameters
+    ----------
+    mesh_gen_params : MeshGenerationParams
+        The parameters to use for mesh generation.
+    geometry : PipelineOutputGeometry
+        The Geometry to mesh.
+
+    Outputs
+    -------
+    mesh : PipelineOutputMesh
+        The generated Mesh.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+    """
+
+    def __init__(
+        self,
+        *,
+        task_name: str | None = None,
+        mesh_gen_params: MeshGenerationParams,
+        geometry: PipelineOutputGeometry,
+    ):
+        super().__init__(
+            task_name,
+            {"mesh_gen_params": mesh_gen_params},
+            OperatorInputs(self, geometry=(PipelineOutputGeometry, geometry)),
+            MeshOutputs._instantiate_for(self),
+        )
+
+
+@dataclass
+class SimulateOutputs(OperatorOutputs):
+    simulation: PipelineOutputSimulation
+    """The Simulation."""
+
+
+@experimental
+class Simulate(Operator[SimulateOutputs]):
+    """
+    Runs a Simulation.
+
+    Parameters
+    ----------
+    sim_template_id : str | StringPipelineParameter
+        The ID of the SimulationTemplate to use for the Simulation.
+    mesh : PipelineOutputMesh
+        The Mesh to use for the Simulation.
+
+    Outputs
+    -------
+    simulation : PipelineOutputSimulation
+        The Simulation.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+    """
+
+    def __init__(
+        self,
+        *,
+        task_name: str | None = None,
+        sim_template_id: str | StringPipelineParameter,
+        mesh: PipelineOutputMesh,
+    ):
+        super().__init__(
+            task_name,
+            {"sim_template_id": sim_template_id},
+            OperatorInputs(self, mesh=(PipelineOutputMesh, mesh)),
+            SimulateOutputs._instantiate_for(self),
+        )