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

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

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

@@ -1,6 +1,7 @@
 # Copyright 2023-2024 Luminary Cloud, Inc. All Rights Reserved.
 from __future__ import annotations
 
+import logging
 import re
 import uuid
 from datetime import datetime
@@ -45,7 +46,8 @@ from .enum import GPUType, MeshType, TableType
 from .meshing import MeshAdaptationParams, MeshGenerationParams
 from .simulation_param import SimulationParam
 from .tables import RectilinearTable, create_rectilinear_table
-from .types import MeshID, ProjectID, SimulationTemplateID
+from .types import MeshID, ProjectID, SimulationTemplateID, NamedVariableSetID, Expression, LcFloat
+from .named_variable_set import get_named_variable_set
 
 if TYPE_CHECKING:
     from .geometry import Geometry
@@ -331,8 +333,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 +353,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 +389,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)
@@ -480,6 +484,7 @@ class Project(ProtoWrapperBase):
         name: str,
         simulation_template_id: str,
         *,
+        _named_variable_set_id: Optional[NamedVariableSetID] = None,
         description: str = "",
         batch_processing: bool = True,
         gpu_type: Optional[GPUType] = None,
@@ -512,12 +517,19 @@ class Project(ProtoWrapperBase):
             Number of GPUs to use for the simulation. Must be specified to a
             positive value if `gpu_type` is specified.
         """
+
+        named_variable_set_version_id: Optional[str] = None
+        if _named_variable_set_id is not None:
+            named_variable_set = get_named_variable_set(_named_variable_set_id)
+            named_variable_set_version_id = named_variable_set._version_id
+
         _simulation = create_simulation(
             get_default_client(),
             self.id,
             mesh_id,
             name,
             simulation_template_id,
+            named_variable_set_version_id=named_variable_set_version_id,
             description=description,
             batch_processing=batch_processing,
             gpu_type=gpu_type,
@@ -548,7 +560,7 @@ class Project(ProtoWrapperBase):
         *,
         parameters: Optional[SimulationParam] = None,
         params_json_path: Optional[PathLike | str] = None,
-        copy_from: Optional["SimulationTemplate" | SimulationTemplateID | str] = None,
+        copy_from: "Optional[SimulationTemplate | SimulationTemplateID | str]" = None,
     ) -> "SimulationTemplate":
         """
         Create a new simulation template object.
@@ -573,11 +585,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
@@ -600,7 +610,7 @@ class Project(ProtoWrapperBase):
 
     @experimental
     def create_named_variable_set(
-        self, name: str, named_variables: dict[str, float | str]
+        self, name: str, named_variables: dict[str, LcFloat]
     ) -> NamedVariableSet:
         """
         Create a new named variable set.
@@ -626,6 +636,47 @@ class Project(ProtoWrapperBase):
         return [lc.NamedVariableSet(n) for n in res.named_variable_sets]
 
 
+@experimental
+def add_named_variables_from_csv(project: Project, csv_path: str) -> list[NamedVariableSet]:
+    """
+    This function reads named variables from a CSV file and creates corresponding NamedVariableSets in the given project.
+    The CSV file should have the following format:
+    name, var1, var2, ...
+    name1, val1, val2, ...
+    name2, val1, val2, ...
+    """
+    import csv
+
+    def is_float(s: str) -> bool:
+        try:
+            float(s)
+            return True
+        except ValueError:
+            return False
+
+    named_variable_sets = []
+    with open(csv_path) as csvfile:
+        reader = csv.reader(csvfile)
+        header = next(reader)
+        keys = [k.strip() for k in header[1:]]
+        for row in reader:
+            if len(row) != len(keys) + 1:
+                logging.warning(
+                    f"Skipping row {row} because it has the wrong number of columns ({len(row)} instead of {len(keys) + 1})"
+                )
+                continue
+            name = row[0]
+            named_variables: dict[str, LcFloat] = {
+                k: float(v.strip()) if is_float(v.strip()) else Expression(v.strip())
+                for k, v in zip(keys, row[1:])
+            }
+            named_variable_sets.append(
+                project.create_named_variable_set(name=name, named_variables=named_variables)
+            )
+            logging.info(f"Created named variable set {name} with {len(named_variables)} variables")
+    return named_variable_sets
+
+
 def create_project(
     name: str,
     description: str = "",

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:
     """