Geometry Product Instance Manager#

Feature highlight#

PyGeometry is a versatile library for geometric modeling and spatial computation, supporting a wide range of applications including shape representation, transformation operations, and spatial analysis across simulations involving multiple physical phenomena.

This example demonstrates how to create a product instance manager for Geometry products using SAF. The product instance manager enables management of the Geometry product instance lifecycle, including starting, stopping, and accessing the product’s API.

In this example, you learn how to:

Launch a Geometry instance from a long-running transaction decorated with @create_instance.
Reuse the running instance in the other transaction methods through the @instance decorator.
Call the Geometry API to extrude a sketch into a slot and to read the active design.
Store the resulting face count, edge count, and design name in typed step fields.
Stream progress messages to the UI with raise_event and a DashClient event listener.
Drive button states and notifications from the event stream, then shut the instance down.

Prerequisites#

Note

This example requires the Geometry 2025 R2 Service Pack 4 (25R2 SP4) product to be installed on your machine. To work with a Geometry product instance, be sure to install the core-pim and instance-management-geometry extras from the ansys-saf-sdk package. You can do this by manually editing your pyproject.toml.

ansys-saf-sdk = {version = "^0.3.0", extras = ["core-pim", "instance-management-geometry"]}

This will install the supported version of ansys-geometry-core to control the Geometry product instances. This example uses PIM as the product instance management system. If you want to use HPS instead, replace the core-pim extra with core-hps. For more information, see Configuration.

Coding#

To create a product instance manager for Geometry products and interact with it, work through the following sequence of sections.

Backend#

Create the solution definition.

Key concept — Product instance manager

A product instance manager wraps a running Ansys product session. The @create_instance decorator starts the product and binds the session to a name, while the @instance decorator injects that same session into any other transaction method.

Key concept — Instance lifecycle

A product instance outlives the transaction method that created it. It stays available to every transaction method of the solution until a transaction explicitly shuts it down.

Key concept — Event stream

self.transaction.raise_event() publishes a message on a named stream. The frontend subscribes to that stream with an event listener, which lets a long-running transaction report its progress without blocking the UI.

Key concept — Termination event

Passing enable_termination_event=True to @transaction makes SAF automatically raise a structured MethodState event on a stream named after the transaction once it completes or fails, so the frontend can track its outcome without parsing log text. launch_geometry, extrude_slot, and get_active_design are long-running and opt into this behavior; shutdown_geometry is a regular transaction and does not raise a termination event.

Define the step model

The launch_geometry long-running transaction is decorated with @create_instance to create an instance of the Geometry product manager, GeometryManager, while the shutdown_geometry transaction is decorated with @instance to reuse and shut down the existing instance. Unlike the other transactions, shutdown_geometry is not long-running and does not raise a termination event.
The extrude_slot and get_active_design transactions are decorated with @instance to indicate they operate on the existing product instance, and call the Geometry API to extrude a slot and to read the active design, respectively.
launch_geometry, extrude_slot, and get_active_design pass enable_termination_event=True so the frontend can track their completion status.

solution/instance_management/geometry_step.py#

    @transaction(self=StepSpec(download=["version"]), enable_termination_event=True)
    @create_instance("geometry_manager", GeometryManager)
    @long_running
    def launch_geometry(self, geometry_manager: GeometryManager) -> None:
        """Launch the Geometry instance and check its availability."""
        self.transaction.raise_event(message="Initializing Geometry instance.", stream_name="geometry-output-stream")
        try:
            geometry_manager.initialize(version=self.version)
        except Exception as e:
            self.transaction.raise_event(
                message=f"Geometry initialization failed: {e}",
                stream_name="geometry-output-stream",
            )
            raise
        self.transaction.raise_event(message="Geometry initialized.", stream_name="geometry-output-stream")

solution/instance_management/geometry_step.py#

    @transaction(self=StepSpec(upload=["body_faces", "body_edges"]), enable_termination_event=True)
    @instance("geometry_manager")
    @long_running
    def extrude_slot(self, geometry_manager: GeometryManager) -> None:
        """Create a slot in the Geometry instance by extruding a sketch."""
        self.transaction.raise_event(message="Starting extrude slot transaction.", stream_name="geometry-output-stream")
        try:
            # Create design on Geometry instance
            design = geometry_manager.instance.create_design("ExtrudeSlot")

            # Create a Sketch object and draw a slot
            sketch = Sketch()
            sketch.slot(Point2D([10, 10], UNITS.mm), Quantity(10, UNITS.mm), Quantity(5, UNITS.mm))  # type: ignore

            # Extrude the sketch
            body = design.extrude_sketch(name="MySlot", sketch=sketch, distance=Distance(50, UNITS.mm))  # type: ignore
            if not body:
                raise RuntimeError("Body was not created.")
            self.body_faces = len(body.faces)
            self.body_edges = len(body.edges)
        except Exception as e:
            self.transaction.raise_event(message=f"Extrude Slot failed: {e}", stream_name="geometry-output-stream")
            raise
        self.transaction.raise_event(message="Extrude Slot succeeded.", stream_name="geometry-output-stream")

solution/instance_management/geometry_step.py#

    @transaction(self=StepSpec(upload=["active_design_name"]), enable_termination_event=True)
    @instance("geometry_manager")
    @long_running
    def get_active_design(self, geometry_manager: GeometryManager) -> None:
        """Get the name of the currently active design."""
        self.transaction.raise_event(message="Getting active design name.", stream_name="geometry-output-stream")
        try:
            self.active_design_name = geometry_manager.instance.read_existing_design().name
            self.transaction.raise_event(
                message=f"Active design name: {self.active_design_name}.",
                stream_name="geometry-output-stream",
            )
        except Exception as e:
            self.transaction.raise_event(message=f"Get active design failed: {e}", stream_name="geometry-output-stream")
            raise
        self.transaction.raise_event(message="Get active design succeeded.", stream_name="geometry-output-stream")

solution/instance_management/geometry_step.py#

    @transaction(self=StepSpec(upload=["geometry_available"]))
    @instance("geometry_manager")
    def shutdown_geometry(self, geometry_manager: GeometryManager) -> None:
        """Close the Geometry instance."""
        self.transaction.raise_event(message="Starting to shutdown the instance.", stream_name="geometry-output-stream")
        try:
            geometry_manager.shutdown()
            self.geometry_available = False
        except Exception as e:
            self.transaction.raise_event(message=f"Geometry shutdown failed: {e}", stream_name="geometry-output-stream")
            raise
        self.transaction.raise_event(
            message="Geometry instance shutdown complete.",
            stream_name="geometry-output-stream",
        )

Frontend#

Expose the solution definition in the UI.

Key concept — Callback

A callback is a Dash-decorated function that fires in response to a UI event. In a SAF solution, callbacks reach the backend through project.steps.<step_name>, read or write fields, and invoke transaction methods. No manual HTTP calls are needed.

Key concept — Event listener

DashClient.create_event_listener() subscribes a page to a backend stream. Each message fires a callback, which is how the console logs and the button states stay in sync with a long-running transaction.

Define the step layout

The layout builds a controls card, with icon buttons to launch and shut down the instance and buttons to extrude a slot and get the active design, and a logs card.
Unlike the other instance management pages, the event listeners are created directly in the layout instead of through a separate mount_event_listeners callback: output-listener subscribes to the free-form progress messages on geometry-output-stream, while launch-geometry-listener, extrude-slot-listener, and get-active-design-listener each subscribe to the termination event of one long-running transaction.