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

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),
+        )

luminarycloud/pipelines/parameters.py

@@ -0,0 +1,42 @@
+# Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
+from .core import PipelineParameter
+
+
+class StringPipelineParameter(PipelineParameter):
+    """
+    A String Pipeline Parameter can replace a hard-coded string in Pipeline operator arguments to
+    allow its value to be set when the Pipeline is invoked.
+    """
+
+    def _type(self) -> str:
+        return "string"
+
+
+class FloatPipelineParameter(PipelineParameter):
+    """
+    A Float Pipeline Parameter can replace a hard-coded float in Pipeline operator arguments to
+    allow its value to be set when the Pipeline is invoked.
+    """
+
+    def _type(self) -> str:
+        return "float"
+
+
+class IntPipelineParameter(PipelineParameter):
+    """
+    An Int Pipeline Parameter can replace a hard-coded int in Pipeline operator arguments to
+    allow its value to be set when the Pipeline is invoked.
+    """
+
+    def _type(self) -> str:
+        return "int"
+
+
+class BoolPipelineParameter(PipelineParameter):
+    """
+    A Bool Pipeline Parameter can replace a hard-coded bool in Pipeline operator arguments to
+    allow its value to be set when the Pipeline is invoked.
+    """
+
+    def _type(self) -> str:
+        return "bool"

luminarycloud/project.py

@@ -331,8 +331,7 @@ class Project(ProtoWrapperBase):
             existing geometry, use MeshGenerationParams. If adapting a mesh from an existing,
             solution use MeshAdaptationParams.
         name : str
-            (Optional) Mesh name. Max 256 characters. Will be ignored if a mesh with the same
-            parameters already exists.
+            Mesh name. Max 256 characters.
         """
 
         try:
@@ -352,6 +351,7 @@ class Project(ProtoWrapperBase):
         self,
         names_to_file_paths: Dict[str, Union[PathLike[Any], str]],
         params: hexmeshpb.HexMeshSpec,
+        use_internal_wrap: bool = False,
     ) -> "Mesh":
         """
         Creates a hex mesh. Only for internal use.
@@ -387,6 +387,8 @@ class Project(ProtoWrapperBase):
         for name, url in names_to_uploaded_file_paths.items():
             params.names_to_file_urls[name] = url
 
+        params.use_wrap = use_internal_wrap
+
         req = meshpb.CreateHexMeshRequest(project_id=self.id, hex_mesh_config=params)
 
         res: meshpb.CreateHexMeshResponse = client.CreateHexMesh(req)
@@ -573,11 +575,9 @@ class Project(ProtoWrapperBase):
             int(params_json_path is not None)
             + int(parameters is not None)
             + int(copy_from is not None)
-            != 1
+            > 1
         ):
-            raise ValueError(
-                "Exactly one of parameters, params_json_path, or copy_from must be set"
-            )
+            raise ValueError("Only one of parameters, params_json_path, or copy_from can be set")
 
         param_proto: clientpb.SimulationParam | None = None
         copy_from_id: str | None = None

luminarycloud/simulation.py

@@ -291,6 +291,10 @@ class Simulation(ProtoWrapperBase):
         return [Solution(s) for s in res.solutions]
 
     def get_parameters(self) -> SimulationParam:
+        """
+        Returns the simulation parameters associated with this simulation to allow customization of
+        the parameters.
+        """
         req = simulationpb.GetSimulationParametersRequest(id=self.id)
         return SimulationParam.from_proto(get_default_client().GetSimulationParameters(req))
 
@@ -298,12 +302,39 @@ class Simulation(ProtoWrapperBase):
         "Use get_parameters() instead. This method will be removed in a future release.",
     )
     def get_simulation_param(self) -> SimulationParam:
-        """
-        Returns the simulation parameters associated with this template to allow customization of
-        the parameters.
-        """
         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.
+import luminarycloud as lc
+
+current_simulation = lc.get_simulation("{self.id}")
+params = current_simulation.get_parameters()
+
+# TODO(USER): Modify the parameters.
+# You can use params.find_parameter to help you find the parameters you wish to modify.
+# params.find_parameter("mach")
+# Alternatively, the Simulation SDK Code shown in the Setup tab, shows how to create the
+# entire params object from scratch. The following line produces a similar result.
+# print(params.to_code())
+
+project = lc.get_project("{self.project_id}")
+# Modify the setup (synced with UI), or an existing template, or create a new one.
+template = project.list_simulation_templates()[0]
+# template = lc.get_simulation_template("...")
+# template = project.create_simulation_template("New Template")
+
+template.update(parameters=params)
+
+# NOTE: This starts a new simulation.
+# This uses the mesh from the current simulation, you can use project.list_meshes() to find
+# other meshes available in the project.
+simulation = project.create_simulation(current_simulation.mesh_id, "New Simulation", template.id)
+# Waiting for the simulation to finish is optional.
+status = simulation.wait()
+"""
+
 
 def get_simulation(id: SimulationID) -> Simulation:
     """

luminarycloud/simulation_param.py

@@ -308,37 +308,41 @@ class SimulationParam(_SimulationParam):
     def __repr__(self) -> str:
         return pformat(vars(self), compact=True, sort_dicts=True)
 
-    def to_code(self, hide_defaults: bool = True) -> str:
+    def to_code(self, hide_defaults: bool = True, use_tmp_objs: bool = True) -> str:
         """
         Returns the python code that generates an identical SimulationParam object.
-        This is a verbose representation that does not make use of helper functions like
+        This is an automatic representation that does not make use of helper functions like
         assign_material and assign_physics.
         Parameters with default values are omitted by default, with hide_defaults=False, code will
         also be generated for those parameters.
+        By default the idiom used to populate lists and maps is to create a temporary object and
+        then append or insert, respectively. The alternative, using [] to access items, is used if
+        use_tmp_objs=False.
         """
-        code = """## NOTE: This is a verbose representation of a SimulationParam object as the
-## code that creates an identical object. The verbosity is intended to facilitate
-## the discovery of available parameters.
+        code = """## NOTE: This is an automatic representation of a SimulationParam object as the
+## code that creates (from scratch) an identical object. As such, some parts do
+## not match 1 to 1 with hand-written examples.
 import luminarycloud
-from luminarycloud import *
 from luminarycloud.types import Vector3
+from luminarycloud.tables import RectilinearTable
 from luminarycloud.enum import *
 from luminarycloud.params.enum import *
-from luminarycloud.params import simulation as params
+from luminarycloud.params import simulation as sim_params
+from luminarycloud import outputs, SimulationParam, EntityIdentifier
 
 
 """
-        return code + self._to_code_helper("obj", hide_defaults).replace(
+        return code + self._to_code_helper("obj", hide_defaults, use_tmp_objs).replace(
             "luminarycloud.simulation_param.SimulationParam()", "SimulationParam()", 1
         )
 
     def find_parameter(self, parameter: str) -> None:
         """
-        Searches the full output of "to_code()" for occurrences of "parameter" and prints the lines
-        with matches. This is a helper function to assist users in finding, for example, how to
-        change farfield conditions, material properties, etc.
+        Searches the full output of "to_code(False, False)" for occurrences of "parameter" and prints
+        the lines with matches. This is a helper function to assist users in finding, for example,
+        how to change farfield conditions, material properties, etc.
         """
-        for i, line in enumerate(self.to_code(False).split("\n")):
+        for i, line in enumerate(self.to_code(False, False).split("\n")):
             if parameter.lower() in line.lower():
                 print(f"line {i}: {line}")
 

luminarycloud/simulation_template.py

@@ -159,7 +159,10 @@ class SimulationTemplate(ProtoWrapperBase):
         get_default_client().DeleteSimulationTemplate(req)
 
     def get_parameters(self) -> SimulationParam:
-        return self.get_simulation_param()
+        """
+        Returns a copy of the simulation parameters associated with this template.
+        """
+        return SimulationParam.from_proto(self._proto.parameters)
 
     @deprecated(
         "Use get_parameters() instead. This method will be removed in a future release.",
@@ -168,7 +171,7 @@ class SimulationTemplate(ProtoWrapperBase):
         """
         Returns a copy of the simulation parameters associated with this template.
         """
-        return SimulationParam.from_proto(self._proto.parameters)
+        return self.get_parameters()
 
     def list_tables(
         self,
@@ -460,20 +463,21 @@ class SimulationTemplate(ProtoWrapperBase):
 
     def to_code(self, hide_defaults: bool = True) -> str:
         """
-        Returns the python code that generates an identical SimulationTemplate object.
+        Returns the python code that generates (from scratch) an identical SimulationTemplate object.
         By default parameters with default values are omitted, this change be changed with
         hide_defaults=False.
         """
-        param_code = self.get_simulation_param().to_code(hide_defaults)
+        param_code = self.get_parameters().to_code(hide_defaults)
         code, param_code = param_code.split("\n\n\n")
 
         # Modify the header note included by SimulationParam.to_code.
         code = code.replace("SimulationParam", "SimulationTemplate")
         code += "\n\n\n"
-        code += '# Create a new simulation template or modify the "Setup" template.\n'
+        code += '# Create a new simulation template or modify the one that is synced with the UI "Setup" tab.\n'
+        code += "# TODO(USER): Replace ... with project ID, or create a project.\n"
         code += 'project = get_project("...")\n'
         code += f"# template = project.create_simulation_template(name={self.name})\n"
-        code += "template = project.list_simulation_templates()[0]\n\n"
+        code += "template = project.list_simulation_templates()[0] # Setup template\n\n"
 
         code += "# Define the simulation parameters.\n"
         code += param_code

luminarycloud/types/vector3.py

@@ -8,10 +8,11 @@ from .adfloat import (
     _to_ad_proto as _float_to_ad_proto,
     _from_ad_proto as _float_from_ad_proto,
 )
+from ..pipeline_util.dictable import PipelineDictable
 
 
 @dataclass
-class Vector3:
+class Vector3(PipelineDictable):
     """Represents a 3-dimensional vector.
 
     Supports direct component access, indexing, iteration, and conversion to numpy arrays.