Geometries#

Geometries are the core of SimAI deep learning-powered predictions. A geometry is a 3D model and the associated metadata managed by the SimAI platform.

File format#

The input format for your workspace is described by the model manifest. You use the workspace.model.geometry attribute to access the information for a specific workspace.

If you have a problem converting to the expected format, contact the SimAI team at support-simai@ansys.com.

Directory#

class GeometryDirectory#

Provides a collection of methods related to geometries.

This class is accessed through client.geometries.

Example

import ansys.simai.core

simai = ansys.simai.core.from_config()
simai.geometries.list()

delete(geometry: Geometry | str) → None#

Delete a specific geometry and its data from the server.

All the objects associated with this geometry (predictions and postprocessings) are also deleted.

Parameters:: geometry (Geometry | str) – ID or model of the geometry.
Raises:: NotFoundError – No geometry with the given ID exists.

See also

Geometry.delete()

Download the geometry with the given ID into the file at the given path.

Parameters:

geometry (Geometry | str) – ID or model of the geometry.
file (BinaryIO | RawIOBase | BufferedIOBase | Path | str | PathLike | None) – Optional binary file-object or the path of the file to put the content into.
monitor_callback (Callable[[int], None] | None) – Optional callback for monitoring the progress of the download. For more information, see the MonitorCallback object.

Returns:

None if a file is provided or a BytesIO object with the geometry’s content otherwise.

Return type:

None | BinaryIO

See also

Geometry.download()

filter(**kwargs: Dict[str, str | float | Range]) → List[Geometry]#

Filter geometries from the server that belong to the currently set workspace.

Parameters:

kwargs (Dict[str, str | float | Range]) –

Filters to apply. Only the elements with matching key-values in their metadata are returned. Each filter can be one of the following data types:

A string
A numerical value (int or float)
A Range condition for filtering values matching a given numerical range of values

Returns:

List of filtered geometries on the server.

Raises:

TypeError – If a Range condition is applied on non-numerical metadata.

Return type:

List[Geometry]

get(name: str | None = None, id: str | None = None, workspace: Workspace | str | None = None) → Geometry#

Get a specific geometry object from the server either by name or ID.

You can specify either the ID or the name, not both.

Parameters:

name (str | None) – Name of the geometry.
id (str | None) – ID of the geometry.
workspace (Workspace | str | None) – ID or model of the workspace containing the geometry. This parameter is necessary if providing a name and no global workspace is set for the client.

Returns:

Geometry.

Raises:

InvalidArguments – If neither a name nor an ID is given.
NotFoundError – If no geometry with the given name or ID exists.

Return type:

Geometry

Examples

Get a geometry by name.

import ansys.simai.core

simai = ansys.simai.core.from_config()
geometry = simai.geometries.get("my_geometry.stl")
# geometry = simai.geometries.get(name="my_geometry.stl") # is equivalent

Get a geometry by ID.

geometry = simai.geometries.get(id="abcdef12")

List geometries from the server that belong to the currently set workspace or the specified one.

Parameters:

workspace (Workspace | str | None) – ID or model of the workspace to list geometries for. This parameter is required if no global workspace is set for the client.
filters (Dict[str, str | float | Range] | None) –
Optional filters. Only the elements with matching key-values in their metadata are returned. Each filter can be one of the following data types:
- A string
- A numerical value (int or float)
- A Range condition for filtering values matching a given numerical range of values

Returns:

List of all or filtered geometries on the server.

Raises:

TypeError – If a Range condition is applied on non-numerical metadata.

Return type:

List[Geometry]

Get the geometries whose metadata are closest to the candidate geometry.

For more information, see the Geometry.sweep() method.

Example

import ansys.simai.core

simai = ansys.simai.core.from_config()
geom = simai.geometries.get("kz19jyqm")
geometries = simai.geometries.sweep(geom, ["length"])

See also

Geometry.sweep()

Upload a geometry to the SimAI platform.

Parameters:

file (Path | str | PathLike | Tuple[BinaryIO | RawIOBase | BufferedIOBase | Path | str | PathLike, str]) – Binary file-object or the path of the geometry to open. For more information, see the NamedFile class.
metadata (Dict[str, Any] | None) – Optional metadata to add to the geometry’s simple key-value store. Lists and nested objects are not supported.
workspace_id – ID or model of the workspace to upload the geometry to. This parameter is only necessary if no workspace is set for the client.
monitor_callback (Callable[[int], None] | None) – Optional callback for monitoring the progress of the download. For more information, see the MonitorCallback object.

Returns:

Created Geometry object.

Return type:

Geometry

Model#

class Geometry#

Provides the local representation of a geometry object.

delete() → None#

Delete the geometry and its data from the server.

All the objects associated with this geometry (predictions and postprocessings) are also deleted.

See also

GeometryDirectory.delete()

Download the geometry into the provided file or in memory if no file is provided.

Parameters:

file (BinaryIO | RawIOBase | BufferedIOBase | Path | str | PathLike | None) – Optional binary file-object or the path of the file to put the content into.
monitor_callback (Callable[[int], None] | None) – Optional callback to monitor the progress of the download. For more information, see the MonitorCallback object.

Returns:

None if a file is provided or the BytesIO object with the geometry’s content otherwise.

Return type:

None | BinaryIO

get_predictions() → List[Prediction]#

Get the prediction objects associated with the geometry.

reload() → None#

Refresh the object with its representation from the server.

rename(name: str) → None#

Change the name of the geometry.

Parameters:: name (str) – New name to give to the geometry.

Note

Only the stem part is modified. The file extension is immutable. If a file extension is provided, it must be the same as the original one. If the new filename already contains dots other than for the extension, the extension must be provided.

run_prediction(boundary_conditions: Dict[str, Number] | None = None, **kwargs) → Prediction#

Run a new prediction or return an existing prediction.

This is a non-blocking method. The prediction object is returned. This object may be incomplete if its computation is not finished, in which case the information is filled once the computation is complete. The state of the computation can be monitored with the prediction’s is_ready attribute or waited upon with its wait() method.

To learn more about the expected boundary conditions in your workspace, you can use the simai.current_workspace.model.boundary_conditions or simai.predictions.boundary_conditions, where ex is your ~ansys.simai.core.client.SimAIClient object.

Parameters:

boundary_conditions (Dict[str, Number] | None) – Boundary conditions to apply as a dictionary.
**kwargs – Boundary conditions to pass as keyword arguments.

Returns:

Created prediction object.

Raises:

ProcessingError – If the server failed to process the request.

Return type:

Prediction

Examples

simai = ansys.simai.core.from_config()
geometry = simai.geometries.list()[0]
geometry.run_prediction(dict(Vx=10.5, Vy=2))

Use kwargs:

prediction = geometry.run_prediction(Vx=10.5, Vy=2)

Return geometries whose metadata are closest to the candidate geometry.

This method returns geometries that have the values closest to the candidate geometry for each considered metadata variable. For example, if sweeping along length and width metadata variables, the method returns geometries that have identical width and the closest smaller and larger length, as well as identical length and the closest smaller and larger width.

The fixed_metadata array allows you to fix one or several variables. For each fixed variable, the resulting geometries must have a metadata value equal to the considered geometry. For example, if fixed_metadata is ["xbow"], every geometry.metadata["xbow"] result must be equal to the candidate_geometry.metadata["xbow"].

Metadata passed neither in swept_metadata nor in fixed_metadata are ignored and can have any value (or absence thereof).

Parameters:

swept_metadata (str | List[str] | None) – Optional metadata name or a list of metadata names to consider. Only variables containing numerical values are supported. If no metadata names are passed, all metadata containing numerical values are taken into account.
fixed_metadata (List[str] | None) – Optional list of metadata variables that should be fixed, meaning that all the resulting geometries have those values equal to the candidate geometry.
geometries (List[Geometry] | None) – Optional list of Geometry objects to consider for sweeping. If no Geometry objects are passed, all geometries are used.
tolerance (float | None) – Optional delta. If the difference between two numbers is lower than the tolerance, they are considered as equal. The default is 10**-6.
order (int | None) – Optional depth of the sweep. The default is 1. This parameter determines the number of returned groups of equal smaller and larger values for each swept variable. For example, if sweeping on a space with lengths [1, 2.1, 2.1, 3.5, 3.5, 4, 4] from the candidate with length=1, order=2 returns the geometries with lengths 2.1, 2.1, 3.5, 3.5.
include_center (bool | None) – Optional Boolean indicating whether geometries with values equal to the candidate geometry (including the candidate itself) are to be returned among the result. The default is False.
include_diagonals (bool | None) – Optional Boolean indicating whether to include diagonals when sweeping on more than one variable. The default is False. For example, if sweeping on two variables from point (0, 0) and with order=1, in addition to (0, 1) and (1, 0), geometry (1, 1) is returned.

Returns:

List of Geometry objects neighboring the candidate geometry for each metadata.

Raises:

ValueError – If a passed variable doesn’t exist in the candidate geometry.
ValueError – If the considered metadata contains non-numerical values or mixed numerical and non numerical values.

Return type:

List[Geometry]

Example

import ansys.simai.core

simai = ansys.simai.core.from_config()
geom = simai.geometries.get("kz19jyqm")
geometries = geom.sweep(["length"])

update_metadata(metadata: Dict[str, str | Number | bool])#

Change the metadata of the geometry.

New keys-values are added.
Existing keys-values are overwritten.
Other key-values are not changed.

To delete a metadata, set it to None explicitly.

Parameters:: metadata (Dict[str, str | Number | bool]) – Dictionary with the new data.

Examples

Add or update a metadata.

geometry.update_metadata({"new_metadata": "value", "existing_metadata": 10})

Remove all metadata.

geometry.update_metadata({key: None for key in geometry.metadata.keys()})

wait(timeout: float | None = None) → bool#

Wait for all jobs concerning the object to either finish or fail.

Parameters:: timeout (float | None) – Maximum amount of time in seconds to wait. The default is None, in means that there is no maximum on the time to wait.
Returns:: True if the computation has finished, False if the operation timed out.
Return type:: bool

property creation_time: str#: Time when the geometry was created in a UTC ISO8601 format string.

property failure_reason#

Optional message giving the causes for why the creation of the object failed.

See also

has_failed

property fields: dict#: Dictionary containing the raw object representation.

property has_failed#

Boolean indicating if the creation of the object failed.

See also

failure_reason
wait()
is_ready
is_pending

property id: str#: ID of the object on the server.

property is_pending#

Boolean indicating if the object is still in creation. The value becomes False once object creation is either successful or has failed.

See also

wait()
is_ready
has_failed

property is_ready#

Boolean indicating if the object has finished creating without error.

See also

wait()
is_pending
has_failed

property metadata: Dict[str, Any]#: User-given key-value associated with the geometry.

property name: str#: Name of the geometry.

Filtering#

class Range#

Describes a numerical range used for filtering geometries.

Range objects describe a numerical range between a minimum and a maximum boundary. Both are optional. Thus, if no maximum boundary is passed, the range describes values greater than or equal to the minimum boundary. Note that ranges are inclusive. Thus, both minimum and maximum boundaries match if they are equal to the passed value (as opposed to Python’s range() method).

Ranges can be used as a filter in the geometries.list method.

Parameters:

min (float | None) – Minimum boundary.
max (float | None) – Maximum boundary.
tolerance (float | None) – Tolerance delta. Two values whose difference is smaller than the tolerance are considered as equal.