luminarycloud 0.22.1__py3-none-any.whl → 0.22.2__py3-none-any.whl

luminarycloud/physics_ai/inference.py

@@ -1,217 +1,184 @@
 # File: python/sdk/luminarycloud/inference/inference.py
 # Copyright 2025 Luminary Cloud, Inc. All Rights Reserved.
-from datetime import datetime
-from typing import Any, Callable, Dict, Optional
-from json import loads as json_loads, dumps as json_dumps
-from dataclasses import dataclass
-import base64
-import os
-import urllib.request
-
-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 typing import Any
+from enum import IntEnum
+from google.protobuf.json_format import MessageToDict
 from .._wrapper import ProtoWrapper, ProtoWrapperBase
-from ..project import Project
-from ..project import Project
-from .._helpers import upload_file
-from .._proto.upload import upload_pb2 as uploadpb
-from ..types.ids import PhysicsAiModelVersionID
+from .._proto.api.v0.luminarycloud.physicsaiinference import (
+    physicsaiinference_pb2 as physicsaiinferencepb,
+)
+from .._proto.base import base_pb2 as basepb
 
 
-@dataclass
-class ExtAeroInferenceResult:
-    """Result of an external aerodynamic inference job.
+class VisualizationOutput(IntEnum):
+    """
+    Represents the type of visualization output.
 
     Attributes
     ----------
-    drag_force: float
-        The drag force returned from the inference.
-    lift_force: float
-        The lift force returned from the inference.
-    wall_shear_stress:
-        A dict containing wall shear stress data, or None if not available.
-    pressure_surface:
-        A dict containing pressure surface stress data, or None if not available.
+    INVALID
+        Invalid visualization output type.
+    LUMINARY
+        Luminary visualization format.
+    VTK
+        VTK visualization format.
     """
 
-    drag_force: float
-    lift_force: float
-    wall_shear_stress: dict[str, Any] | None
-    pressure_surface: dict[str, Any] | None
-
-    def __init__(self, inference_result: dict[str, Any]) -> None:
-        self.drag_force = inference_result["drag_force"]
-        self.lift_force = inference_result["lift_force"]
-        self.wall_shear_stress = inference_result.get("wall-shear-stress", None)
-        self.pressure_surface = inference_result.get("pressure_surface", None)
-
-
-def external_aero_inference(
-    project: Project,
-    stl_file: str,
-    model_version_id: PhysicsAiModelVersionID,
-    conditions: Optional[Dict[str, Any]] = None,
-    settings: Optional[Dict[str, Any]] = None,
-    write_visualization_data=False,
-) -> ExtAeroInferenceResult:
-    """Performs an inference job returning external aerodynamic results.
-    Parameters
-    ----------
-    project : Project
-        The project to which the inference files will be added.
-    stl_file : str
-        Fullpath the STL file to be used for inference.
-    model_version_id : PhysicsAiModelVersionID
-        The ID of the trained model version to use for inference.
-    conditions : Dict[str, Any], optional
-        Dictionary of conditions to be passed to the inference service (e.g., alpha, beta, etc.).
-    settings : Dict[str, Any], optional
-        Dictionary of settings to be passed to inference service (e.g., stencil_size)
-    write_visualization_data : bool, optional
-        Whether to write LC visualization data for visualization by Luminary.
-
-
-    Returns
-    ExtAeroInferenceResult
-        Result of the external aerodynamic inference job.
-
-    warning:: This feature is experimental and may change or be removed without notice.
+    INVALID = physicsaiinferencepb.INVALID
+    LUMINARY = physicsaiinferencepb.LUMINARY
+    VTK = physicsaiinferencepb.VTK
+
+
+class InferenceFieldType(IntEnum):
     """
+    Represents the type of an inference field.
 
-    result = perform_inference(
-        project, stl_file, model_version_id, conditions, settings, write_visualization_data
-    )
-    return ExtAeroInferenceResult(result)
-
-
-def perform_inference(
-    project: Project,
-    stl_file: str,
-    model_version_id: PhysicsAiModelVersionID,
-    conditions: Optional[Dict[str, Any]] = None,
-    settings: Optional[Dict[str, Any]] = None,
-    write_visualization_data=False,
-) -> dict[str, Any]:
-    """Creates an inference service job.
-    Parameters
+    Attributes
     ----------
-    project : Project
-        The project to which the inference files will be added.
-    stl_file : str
-        Fullpath the STL file to be used for inference.
-    model_version_id : PhysicsAiModelVersionID
-        The ID of the trained model version to use for inference.
-    conditions : Dict[str, Any], optional
-        Dictionary of conditions to be passed to the inference service (e.g., alpha, beta, etc.).
-    settings : Dict[str, Any], optional
-        Dictionary of settings to be passed to inference service (e.g., stencil_size)
-    write_visualization_data : bool, optional
-        Whether to write LC visualization data for visualization by Luminary.
-
-
-    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.
+    UNKNOWN_TYPE
+        Unknown field type.
+    SCALAR
+        Scalar field type (single value).
+    VECTOR
+        Vector field type (multiple values).
     """
 
-    client = get_default_client()
-
-    def upload_if_file(fname: str) -> str:
-        if os.path.exists(fname) and os.path.isfile(fname):
-            params = uploadpb.ResourceParams()
-            result = upload_file(client, project.id, params, fname)
-            return result[1].url
-        if fname.startswith("gs://"):
-            return fname
-        raise RuntimeError("Unsupported file for inference")
-
-    def future_file(url: str) -> Callable[[], dict[str, Any]]:
-        def download_file() -> dict[str, Any]:
-            with urllib.request.urlopen(url) as f:
-                serialized = f.read()
-                jsondata = json_loads(serialized)
-                data = base64.b64decode(jsondata["data"])
-                jsondata["data"] = data
-                return jsondata
-
-        return download_file
-
-    stl_url = upload_if_file(stl_file)
-
-    raw = start_inference_job(
-        project, stl_url, model_version_id, conditions, settings, write_visualization_data
-    )
-    currated: dict[str, Any] = {}
-    for k, v in raw.items():
-        if isinstance(v, str) and v.startswith("https://"):
-            tmp = future_file(v)
-            if k.endswith("_url"):
-                currated[k[:-4]] = tmp
-                currated[k] = v
-            else:
-                currated[k] = tmp
-                currated[k + "_url"] = v
-        else:
-            currated[k] = v
-    return currated
-
-
-def start_inference_job(
-    project: Project,
-    stl_url: str,
-    model_version_id: PhysicsAiModelVersionID,
-    conditions: Optional[Dict[str, Any]] = None,
-    settings: Optional[Dict[str, Any]] = None,
-    write_visualization_data=False,
-) -> dict[str, Any]:
-    """Creates an inference service job.
-    Parameters
+    UNKNOWN_TYPE = physicsaiinferencepb.UNKNOWN_TYPE
+    SCALAR = physicsaiinferencepb.SCALAR
+    VECTOR = physicsaiinferencepb.VECTOR
+
+
+class InferenceFieldCategory(IntEnum):
+    """
+    Represents the category of an inference field.
+
+    Attributes
     ----------
-    project : Project
-        Reference to a project.
-    stl_url : str
-        URL of the STL file to be used for inference.
-    model_version_id : PhysicsAiModelVersionID
-        The ID of the trained model version to use for inference.
-    conditions : Dict[str, Any], optional
-        Dictionary of conditions to be passed to the inference service (e.g., alpha, beta, etc.).
-    settings : Dict[str, Any], optional
-        Dictionary of settings to be passed to inference service (e.g., stencil_size)
-    write_visualization_data : bool, optional
-        Whether to write LC visualization data for visualization by Luminary.
-
-
-    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.
+    UNKNOWN_CATEGORY
+        Unknown field category.
+    NUMERIC
+        Numeric field category (e.g., forces, moments).
+    SURFACE
+        Surface field category (e.g., surface pressure).
+    VOLUME
+        Volume field category (e.g., velocity, pressure).
     """
 
-    # Embed settings and store as bytes
-    settings_bytes = b""
-    if settings is not None:
-        settings_bytes = json_dumps(settings).encode("utf-8")
-
-    # Convert parameters dict to bytes if provided
-    conditions_bytes = b""
-    if conditions is not None:
-        conditions_bytes = json_dumps(conditions).encode("utf-8")
-
-    req = inferencepb.CreateInferenceServiceJobRequest(
-        stl_url=stl_url,
-        model_version_id=str(model_version_id),
-        conditions=conditions_bytes,
-        settings=settings_bytes,
-        project_id=project.id,
-        write_visualization_data=write_visualization_data,
-    )
-    res: inferencepb.CreateInferenceServiceJobResponse = (
-        get_default_client().CreateInferenceServiceJob(req)
-    )
-
-    return json_loads(str(res.response, encoding="utf-8"))
+    UNKNOWN_CATEGORY = physicsaiinferencepb.UNKNOWN_CATEGORY
+    NUMERIC = physicsaiinferencepb.NUMERIC
+    SURFACE = physicsaiinferencepb.SURFACE
+    VOLUME = physicsaiinferencepb.VOLUME
+
+
+@ProtoWrapper(physicsaiinferencepb.VisualizationExport)
+class VisualizationExport(ProtoWrapperBase):
+    """Represents a visualization export."""
+
+    type: VisualizationOutput
+    url: str
+    _proto: physicsaiinferencepb.VisualizationExport
+
+    def get_url(self) -> str:
+        return self.url
+
+
+@ProtoWrapper(physicsaiinferencepb.NumericResult)
+class NumericResult(ProtoWrapperBase):
+    """Represents a numeric result."""
+
+    scalar: float
+    vector: list[float]
+    _proto: physicsaiinferencepb.NumericResult
+
+    def get_value(self) -> Any:
+        if self._proto.HasField("scalar"):
+            return self.scalar
+        if self._proto.HasField("vector"):
+            return list(self._proto.vector.values)
+        return None
+
+
+@ProtoWrapper(physicsaiinferencepb.SurfaceForInference)
+class SurfaceForInference(ProtoWrapperBase):
+    """Represents a surface for inference."""
+
+    name: str
+    url: str
+    _proto: physicsaiinferencepb.SurfaceForInference
+
+    def get_name(self) -> str:
+        return self.name
+
+    def get_url(self) -> str:
+        return self.url
+
+
+@ProtoWrapper(physicsaiinferencepb.InferenceResult)
+class InferenceResult(ProtoWrapperBase):
+    """Represents an inference result."""
+
+    name: str
+    surface_results: dict[str, str]
+    volume_results: dict[str, str]
+    visualizations: list[VisualizationExport]
+
+    @property
+    def number_outputs(self) -> dict[str, NumericResult]:
+        """Returns number_outputs with wrapped NumericResult values."""
+        return {k: NumericResult(v) for k, v in self._proto.number_outputs.items()}
+
+    def get_number_outputs(self) -> dict[str, Any]:
+        return MessageToDict(self._proto.number_outputs, preserving_proto_field_name=True)
+
+    def get_surface_results(self) -> dict[str, Any]:
+        return MessageToDict(self.surface_results, preserving_proto_field_name=True)
+
+    def get_volume_results(self) -> dict[str, Any]:
+        return MessageToDict(self.volume_results, preserving_proto_field_name=True)
+
+    def get_visualizations(self) -> list[dict[str, Any]]:
+        return [
+            MessageToDict(viz._proto, preserving_proto_field_name=True)
+            for viz in self.visualizations
+        ]
+
+
+@ProtoWrapper(physicsaiinferencepb.InferenceServiceJob)
+class InferenceJob(ProtoWrapperBase):
+    """Represents an inference service job."""
+
+    job_id: str
+    status: basepb.JobStatus
+    results: list[InferenceResult]
+    merged_visualizations: list[VisualizationExport]
+    _proto: physicsaiinferencepb.InferenceServiceJob
+
+    @property
+    def id(self) -> str:
+        """Alias for job_id for convenience."""
+        return self.job_id
+
+    def get_status(self) -> str:
+        return basepb.JobStatusType.Name(self.status.typ)
+
+    def get_results(self) -> list[dict[str, Any]]:
+        return [
+            MessageToDict(result._proto, preserving_proto_field_name=True)
+            for result in self.results
+        ]
+
+    def get_merged_visualizations(self) -> list[dict[str, Any]]:
+        return [
+            MessageToDict(viz._proto, preserving_proto_field_name=True)
+            for viz in self.merged_visualizations
+        ]
+
+
+@ProtoWrapper(physicsaiinferencepb.InferenceField)
+class InferenceField(ProtoWrapperBase):
+    """Represents an inference field."""
+
+    name: str
+    type: InferenceFieldType
+    category: InferenceFieldCategory
+    _proto: physicsaiinferencepb.InferenceField

luminarycloud/physics_ai/models.py

@@ -3,6 +3,9 @@ from typing import List, Optional
 
 from .._client import get_default_client
 from .._proto.api.v0.luminarycloud.physics_ai import physics_ai_pb2 as physaipb
+from .._proto.api.v0.luminarycloud.physicsaiinference import (
+    physicsaiinference_pb2 as physicsaiinferencepb,
+)
 from .._wrapper import ProtoWrapper, ProtoWrapperBase
 from ..types.ids import PhysicsAiModelID, PhysicsAiModelVersionID
 from ..enum.physics_ai_lifecycle_state import PhysicsAiLifecycleState
@@ -21,6 +24,25 @@ class PhysicsAiModelVersion(ProtoWrapperBase):
     lifecycle_state: PhysicsAiLifecycleState
     _proto: physaipb.PhysicsAiModelVersion
 
+    def get_inference_fields(self) -> list[str]:
+        """Gets the inference fields available for a trained model version.
+
+        This retrieves the list of output fields that can be requested from a specific
+        model version during inference.
+
+        Returns
+        -------
+        list[str]
+            List of available inference field names that can be requested from the model.
+
+        warning:: This feature is experimental and may change or be removed without notice.
+        """
+        req = physicsaiinferencepb.GetInferenceFieldsRequest(model_version_id=str(self.id))
+        res: physicsaiinferencepb.GetInferenceFieldsResponse = (
+            get_default_client().GetInferenceFields(req)
+        )
+        return list(res.inference_fields)
+
 
 @ProtoWrapper(physaipb.PhysicsAiModel)
 class PhysicsAiModel(ProtoWrapperBase):

luminarycloud/pipelines/api.py

@@ -10,6 +10,7 @@ from .arguments import PipelineArgValueType
 from .core import Stage
 from ..pipelines import Pipeline, PipelineArgs
 from .._client import get_default_client
+from .._helpers import parse_iso_datetime
 
 logger = logging.getLogger(__name__)
 
@@ -23,7 +24,7 @@ class LogLine:
     @classmethod
     def from_json(cls, json: dict) -> "LogLine":
         return cls(
-            timestamp=datetime.fromisoformat(json["timestamp"]),
+            timestamp=parse_iso_datetime(json["timestamp"]),
             level=json["level"],
             message=json["message"],
         )
@@ -54,8 +55,8 @@ class PipelineRecord:
             name=json["name"],
             description=json["description"],
             definition_yaml=json["definition_yaml"],
-            created_at=datetime.fromisoformat(json["created_at"]),
-            updated_at=datetime.fromisoformat(json["updated_at"]),
+            created_at=parse_iso_datetime(json["created_at"]),
+            updated_at=parse_iso_datetime(json["updated_at"]),
         )
 
     def pipeline_jobs(self) -> "list[PipelineJobRecord]":
@@ -100,11 +101,12 @@ class PipelineJobRecord:
     pipeline_id: str
     name: str
     description: str | None
-    status: Literal["pending", "running", "completed", "failed", "cancelled"]
+    status: Literal["pending", "running", "completed", "failed", "cancelled", "paused"]
     created_at: datetime
     updated_at: datetime
     started_at: datetime | None
     completed_at: datetime | None
+    paused_at: datetime | None
 
     @classmethod
     def from_json(cls, json: dict) -> "PipelineJobRecord":
@@ -112,14 +114,15 @@ class PipelineJobRecord:
             id=json["id"],
             pipeline_id=json["pipeline_id"],
             name=json["name"],
-            description=json["description"],
+            description=json.get("description"),
             status=json["status"],
-            created_at=datetime.fromisoformat(json["created_at"]),
-            updated_at=datetime.fromisoformat(json["updated_at"]),
-            started_at=datetime.fromisoformat(json["started_at"]) if json["started_at"] else None,
+            created_at=parse_iso_datetime(json["created_at"]),
+            updated_at=parse_iso_datetime(json["updated_at"]),
+            started_at=(parse_iso_datetime(json["started_at"]) if json.get("started_at") else None),
             completed_at=(
-                datetime.fromisoformat(json["completed_at"]) if json["completed_at"] else None
+                parse_iso_datetime(json["completed_at"]) if json.get("completed_at") else None
             ),
+            paused_at=(parse_iso_datetime(json["paused_at"]) if json.get("paused_at") else None),
         )
 
     def pipeline(self) -> PipelineRecord:
@@ -315,6 +318,39 @@ class PipelineJobRecord:
         get_default_client().http.post(f"/rest/v0/pipeline_jobs/{self.id}/cancel", {})
         logger.info(f"Cancelled pipeline job {self.id}")
 
+    def pause(self) -> None:
+        """Pause this running pipeline job.
+
+        This will prevent new tasks from being scheduled while allowing
+        in-progress tasks to complete. The job status will be set to PAUSED
+        and all stage concurrency limits will be temporarily set to 0.
+
+        Call resume() to continue execution.
+
+        Raises
+        ------
+        HTTPError
+            If the pipeline job cannot be paused (e.g., not found or not in
+            RUNNING state).
+        """
+        get_default_client().http.post(f"/rest/v0/pipeline_jobs/{self.id}/pause", {})
+        logger.info(f"Paused pipeline job {self.id}")
+
+    def resume(self) -> None:
+        """Resume this paused pipeline job.
+
+        This will restore the job status to RUNNING and restore the original
+        concurrency limits, allowing new tasks to be scheduled again.
+
+        Raises
+        ------
+        HTTPError
+            If the pipeline job cannot be resumed (e.g., not found or not in
+            PAUSED state).
+        """
+        get_default_client().http.post(f"/rest/v0/pipeline_jobs/{self.id}/resume", {})
+        logger.info(f"Resumed pipeline job {self.id}")
+
 
 @dataclass
 class PipelineJobRunRecord:

luminarycloud/project.py

@@ -25,6 +25,10 @@ from ._helpers import (
     upload_file,
     upload_mesh,
     upload_table_as_json,
+    create_inference_job,
+    get_inference_job,
+    list_inference_jobs,
+    SurfaceForInference,
 )
 from ._helpers.warnings import deprecated
 from ._proto.api.v0.luminarycloud.geometry import geometry_pb2 as geometrypb
@@ -47,10 +51,20 @@ from ._proto.upload import upload_pb2 as uploadpb
 from ._wrapper import ProtoWrapper, ProtoWrapperBase
 from .enum import GPUType, MeshType, TableType
 from .meshing import MeshAdaptationParams, MeshGenerationParams
+from .named_variable_set import NamedVariableSet, get_named_variable_set
+from .physics_ai.inference import InferenceJob, VisualizationExport
 from .simulation_param import SimulationParam
 from .tables import RectilinearTable, create_rectilinear_table
-from .types import MeshID, ProjectID, SimulationTemplateID, NamedVariableSetID, Expression, LcFloat
-from .named_variable_set import get_named_variable_set
+from .types import (
+    MeshID,
+    ProjectID,
+    SimulationTemplateID,
+    NamedVariableSetID,
+    Expression,
+    LcFloat,
+    PhysicsAiInferenceJobID,
+    PhysicsAiModelVersionID,
+)
 
 if TYPE_CHECKING:
     from .geometry import Geometry
@@ -701,6 +715,46 @@ class Project(ProtoWrapperBase):
         req = projectpb.UnshareProjectWithSupportRequest(id=self.id)
         get_default_client().UnshareProjectWithSupport(req)
 
+    def create_inference_job(
+        self,
+        geometry: str,
+        model_version_id: PhysicsAiModelVersionID,
+        synchronous: bool = False,
+        conditions: Optional[Dict[str, Any]] = None,
+        settings: Optional[Dict[str, Any]] = None,
+        surfaces: Optional[list[SurfaceForInference]] = None,
+        inference_fields: Optional[list[str]] = None,
+        per_surface_visualizations: Optional[list[VisualizationExport]] = None,
+        merged_visualizations: Optional[list[VisualizationExport]] = None,
+    ) -> InferenceJob:
+        """
+        Create a new Physics AI inference job.
+        """
+        return create_inference_job(
+            self.id,
+            geometry,
+            model_version_id,
+            synchronous,
+            conditions,
+            settings,
+            surfaces,
+            inference_fields,
+            per_surface_visualizations,
+            merged_visualizations,
+        )
+
+    def get_inference_job(self, job_id: PhysicsAiInferenceJobID) -> InferenceJob:
+        """
+        Get a Physics AI inference job by its ID.
+        """
+        return get_inference_job(job_id)
+
+    def list_inference_jobs(self) -> list[InferenceJob]:
+        """
+        List all inference jobs for the project.
+        """
+        return list_inference_jobs(self.id)
+
 
 def add_named_variables_from_csv(project: Project, csv_path: str) -> list[NamedVariableSet]:
     """

luminarycloud/simulation.py

@@ -22,6 +22,7 @@ from .enum import (
     SimulationStatus,
     Vector3Component,
 )
+from .outputs.stopping_conditions import StoppingConditionStatusResult
 from .simulation_param import SimulationParam
 from .reference_values import ReferenceValues
 from .simulation_param import SimulationParam
@@ -324,6 +325,30 @@ class Simulation(ProtoWrapperBase):
         result = _get_workflow_ids([self.id])
         return result.get(self.id)
 
+    def get_stopping_condition_status(self) -> StoppingConditionStatusResult:
+        """
+        Retrieves the stopping condition status for a completed simulation.
+
+        This evaluates the stopping conditions defined in the simulation parameters
+        against the final simulation results to determine which conditions were satisfied.
+
+        Returns
+        -------
+        StoppingConditionStatusResult
+            The stopping condition status containing:
+            - overall_success: Whether the overall stopping criteria were met
+            - force_stopped: Whether a force-stop condition was triggered
+            - condition_results: Results for each individual condition (output name, threshold, value, satisfied)
+
+        Raises
+        ------
+        SDKException
+            If the simulation has not completed or the status cannot be retrieved.
+        """
+        req = simulationpb.GetStoppingConditionStatusRequest(id=self.id)
+        res = get_default_client().GetStoppingConditionStatus(req)
+        return StoppingConditionStatusResult._from_proto(res)
+
     @deprecated(
         "Use get_parameters() instead. This method will be removed in a future release.",
     )

luminarycloud/types/__init__.py

@@ -7,6 +7,8 @@ from .ids import (
     SimulationTemplateID as SimulationTemplateID,
     GeometryFeatureID as GeometryFeatureID,
     NamedVariableSetID as NamedVariableSetID,
+    PhysicsAiInferenceJobID as PhysicsAiInferenceJobID,
+    PhysicsAiModelVersionID as PhysicsAiModelVersionID,
 )
 
 from .adfloat import (

luminarycloud/types/ids.py

@@ -11,5 +11,7 @@ GeometryFeatureID = NewType("GeometryFeatureID", str)
 NamedVariableSetID = NewType("NamedVariableSetID", str)
 PhysicsAiArchitectureID = NewType("PhysicsAiArchitectureID", str)
 PhysicsAiArchitectureVersionID = NewType("PhysicsAiArchitectureVersionID", str)
+PhysicsAiInferenceJobID = NewType("PhysicsAiInferenceJobID", str)
 PhysicsAiModelID = NewType("PhysicsAiModelID", str)
 PhysicsAiModelVersionID = NewType("PhysicsAiModelVersionID", str)
+PhysicsAiTrainingJobID = NewType("PhysicsAiTrainingJobID", str)

luminarycloud/vis/__init__.py

@@ -22,6 +22,7 @@ from .primitives import (
 
 from .filters import (
     Slice as Slice,
+    MultiSlice as MultiSlice,
     PlaneClip as PlaneClip,
     BoxClip as BoxClip,
     FixedSizeVectorGlyphs as FixedSizeVectorGlyphs,