scivianna.interface package

Scivianna Interface Module

The interface module provides data interfaces for reading simulation results from various file formats. Interfaces abstract data access and provide a unified API for visualization.

Files

File	Description
`__init__.py`	Package initialization file, registers available interfaces
`generic_interface.py`	Base class `GenericInterface` with common functionality
`med_interface.py`	Interface for Salome MED file format
`vtk_interface.py`	Interface for VTK/VTU file formats
`csv_result.py`	Interface for CSV time-series data
`structured_mesh_interface.py`	Interface for structured mesh data
`time_dataframe.py`	Utility class for time-indexed data frames

Interface Hierarchy

GenericInterface (Base Class)

Provides core functionality for all interfaces:

Function	Description
`read_file(file_path, file_label)`	Reads input files to extract data
`get_labels()`	Returns list of available fields/results
`get_label_coloring_mode(label)`	Returns whether a field is colored by string or float values
`get_file_input_list()`	Returns list of loaded files with descriptions
`serialize(obj, key)`	Serializes objects for multiprocessing queue transmission
`save(file_path, include_files)`	Saves interface state to a pickle file
`load(file_path, include_files)`	Loads interface state from a pickle file
`get_slave()`	Returns a ComputeSlave instance for the interface class

Data Capability Interfaces

Interfaces inherit from these capability classes based on what they provide:

Interface	Purpose
`Geometry2D`	Provides 2D cell geometry and field values
`Geometry2DPolygon`	Provides 2D geometry as a list of polygons
`Geometry2DGrid`	Provides 2D geometry as a numpy array (rasterized)
`ValueAtLocation`	Provides values at specific locations/cells/materials
`Value1DAtLocation`	Provides 1D data profiles at locations
`OverLine`	Extracts data along user-defined lines
`CouplingInterface`	Supports runtime coupling updates (C3PO/Icoco)

Geometry2D Interface

Extends GenericInterface with 2D geometry capabilities:

Function	Description
`compute_2D_data(u, v, u_min, u_max, v_min, v_max, w_value, q_tasks, options, caller)`	Returns 2D geometry polygons for a given frame
`get_value_dict(value_label, cells, options, caller)`	Returns cell name to field value mapping

Geometry2DPolygon Interface

Subclass of Geometry2D that provides polygon-based geometry. Inherits all Geometry2D methods.

Geometry2DGrid Interface

Subclass of Geometry2D that provides grid-based (rasterized) geometry. Inherits all Geometry2D methods.

ValueAtLocation Interface

Provides point-value access capabilities:

Function	Description
`get_value(position, cell_index, material_name, field, options)`	Returns field value at a specific location/cell/material
`get_values(positions, cell_indexes, material_names, field, options)`	Returns field values at multiple locations/cells/materials

Value1DAtLocation Interface

Provides 1D data profile access:

Function	Description
`get_1D_value(position, cell_index, material_name, field, options)`	Returns 1D data series (pd.Series) at a specific location/cell/material

OverLine Interface

Provides line-based data extraction:

Function	Description
`compute_1D_line_data(pos, u, d, q_tasks, options)`	Returns field values along a 1D line as a pandas DataFrame

CouplingInterface

Provides runtime coupling capabilities for C3PO/Icoco integration:

Function	Description
`set_time(time)`	Sets the current time for coupling updates
`update_data(key, data)`	Replaces interface data with new value
`append_data(key, data)`	Appends data associated with current time
`update_mesh(key, data)`	Replaces interface mesh and data with new value
`append_mesh(key, data)`	Appends mesh and data associated with current time
`get_template(name)`	Returns template for C3PO getOutputxxxFieldTemplate functions
`set_template(name, template)`	Sets the template for C3PO functions

Available Interfaces

MED Interface

Reads Salome MED files containing:

Mesh geometry (2D/3D)
Field data on cells/nodes
Time-step information

from scivianna.interface.med_interface import MEDInterface

interface = MEDInterface()
interface.read_file("result.med")
labels = interface.get_labels()  # ["temperature", "pressure", ...]

VTK Interface

Reads VTK/VTU files for unstructured grids:

Polygon/polyhedron cells
Point and cell data
Multiple time steps

CSV Interface

Reads structured CSV data:

Time-series results
Column-based variables
Automatic parsing with pandas

Creating Custom Interfaces

Custom interfaces can be easily created, the scivianna.interface.generic_interface file defines what functions need to be provided for a new interface.

from scivianna.interface.generic_interface import GenericInterface, Geometry2D

class MyCustomInterface(GenericInterface, Geometry2D):
    def read_file(self, filepath):
        # Implement file reading logic
        pass
    
    def get_labels(self):
        # Return available field names
        return ["field1", "field2"]
    
    def get_geometry_2d(self, field_name):
        # Return 2D geometry for the field
        pass

Interface Registration

Built-in interfaces are automatically discovered and registered via __init__.py. Additional user interfaces can be implemeted by calling:

from scivianna.interface import register_interface

register_interface("MyInterfaceKey", MyInterfaceClass)

Submodules

scivianna.interface.csv_result module

scivianna.interface.generic_interface module

class scivianna.interface.generic_interface.CouplingInterface

Bases: GenericInterface

Interface parent class to implement the C3PO functions required for a code coupling visualization.

append_data(key: str, data: Any)

Stores the data and associates it to the current time.

Parameters:

key (str) – Data associated key
data (Any) – New value

append_mesh(key: str, data: Any)

Stores the data and mesh and associate them to the current time.

Parameters:

key (str) – Data associated key
data (Any) – New value

get_template(name: str)

Returns the template for the C3PO getOutputxxxFieldTemplate functions

Parameters:: name (str) – Field name

set_template(name: str, template: Any)

Sets the template returned by C3PO getOutputxxxFieldTemplate functions

Parameters:

name (str) – Field name
template (Any) – Object to set as template

set_time(time: float)

This non-Icoco function allows setting the current time in an interface to associate to the received value.

Parameters:: time (float) – Current time

update_data(key: str, data: Any)

Replaces the interface data by the current value

Parameters:

key (str) – Data associated key
data (Any) – New value

update_mesh(key: str, data: Any)

Replaces the interface data and mesh by the current value

Parameters:

key (str) – Data associated key
data (Any) – New value

class scivianna.interface.generic_interface.GenericInterface

Bases: object

Generic interface class that implement basic functions. This class mutualises functions that are shared between its child classes.

extensions = []: Extensions associated to this interface.

get_file_input_list() → List[Tuple[str, str]]

Returns a list of file label and its description for the GUI

Returns:: List of (file label, description)
Return type:: List[Tuple[str, str]]
Raises:: NotImplementedError – The function was not implemented in the code interface.

get_label_coloring_mode(label: str) → VisualizationMode

Returns wheter the given field is colored based on a string value or a float.

Parameters:: label (str) – Field to color name
Returns:: Coloring mode
Return type:: VisualizationMode
Raises:: NotImplementedError – Function to override in the code interfaces

get_labels() → List[str]

Returns a list of fields names displayable with this interface

Returns:: List of fields names
Return type:: List[str]

classmethod get_slave()

load(file_path: Path, include_files: bool)

Pickle loads the slave content to a file, allows slave state reload

Two modes are available:

If include_files is at True, all loaded data are saved, the pickled file can be loaded on its own to recover last session.
If include_files is at False, only the computed data are loaded, enabling faster first computation allowing a smaller pickle file size.

Parameters:

file_path (Path) – File from which load the slave
include_files (bool) – Included loaded file

read_file(file_path: str, file_label: str) → None

Read a file and store its content in the interface

Parameters:

file_path (str) – File to read
file_label (str) – Label to define the file type

Raises:

NotImplementedError – Function to override in the code interfaces

save(file_path: Path, include_files: bool)

Pickle saves the slave content to a file, allows slave state reload.

Two modes are available:

If include_files is at True, all loaded data are saved, the pickled file can be loaded on its own to recover last session.
If include_files is at False, only the computed data are loaded, enabling faster first computation allowing a smaller pickle file size.

Parameters:

file_path (Path) – File in which save the file
include_files (bool) – Included loaded file

classmethod serialize(obj: Any, key: str) → Any

This function receives an object that is about to be transmitted at the given key. - If the object can be passed through a python multiprocessing Queue, it can be returned. - If the object can’t, it is serialized, and the code returns the file path.

The read function will then be able to expect the returned object at the given key.

By default, this class returns the obj, if the cobject can’t be passed, overwrite this function.

Parameters:

obj (Any) – Object that is sent to the generic interface
key (str) – Key associated to the object

Returns:

Object transmissible through a multiprocessing Queue associated to the given object.

Return type:

Any

class scivianna.interface.generic_interface.Geometry2D

Bases: GenericInterface

Interface parent class for classes that can compute geometry 2D slices.

compute_2D_data(u: Tuple[float, float, float], v: Tuple[float, float, float], u_min: float, u_max: float, v_min: float, v_max: float, w_value: float, q_tasks: Queue, options: Dict[str, Any], caller: str = 'API') → Tuple[Data2D, bool]

Returns a list of polygons that defines the geometry in a given frame

Parameters:

u (Tuple[float, float, float]) – Horizontal coordinate director vector
v (Tuple[float, float, float]) – Vertical coordinate director vector
u_min (float) – Lower bound value along the u axis
u_max (float) – Upper bound value along the u axis
v_min (float) – Lower bound value along the v axis
v_max (float) – Upper bound value along the v axis=
w_value (float) – Value along the u ^ v axis
q_tasks (mp.Queue) – Queue from which get orders from the master.
options (Dict[str, Any]) – Additional options for frame computation.
caller (str) – Identifier of the caller requesting the computation (default: “API”)

Returns:

Data2D – Geometry to display
bool – Were the polygons updated compared to the past call

Raises:

NotImplementedError – Function to override in the code interfaces

data_type: DataType: Enum saying if the data are returned in a 2D grid or a polygon list

geometry_type: GeometryType: Enum telling if the geometry is 2D or 3D (Displays the axis card and the w coordinate in the GUI).

get_value_dict(value_label: str, cells: List[int | str], options: Dict[str, Any], caller: str = 'API') → Dict[int | str, str]

Returns a cell name - field value map for a given field name

Parameters:

value_label (str) – Field name to get values from
cells (List[Union[int,str]]) – List of cells names
options (Dict[str, Any]) – Additional options for frame computation.
caller (str) – Identifier of the caller requesting the computation (default: “API”)

Returns:

Field value for each requested cell names

Return type:

Dict[Union[int,str], str]

Raises:

NotImplementedError – Function to override in the code interfaces

rasterized: bool = False: Boolean telling if the geometry is made by rasterizing a 2D grid (displays the line count in the GUI).

class scivianna.interface.generic_interface.Geometry2DGrid

Bases: Geometry2D

Interface parent class for classes that can compute geometry 2D slices and provide a numpy array.

rasterized: bool = True: Boolean telling if the geometry is made by rasterizing a 2D grid (displays the line count in the GUI).

class scivianna.interface.generic_interface.Geometry2DPolygon

Bases: Geometry2D

Interface parent class for classes that can compute geometry 2D slices and provide a list of polygons.

class scivianna.interface.generic_interface.OverLine

Bases: GenericInterface

Interface parent class to implement a function to compute a field value along a 1D line.

compute_1D_line_data(pos: Tuple[float, float, float], u: Tuple[float, float, float], d: float, q_tasks: Queue, options: Dict[str, Any]) → DataFrame

Returns a list of polygons that defines the geometry in a given frame

Parameters:

pos (Tuple[float, float, float]) – 1D data line start location
u (Tuple[float, float, float]) – Data line direction vector
d (float) – Distance to travel by the 1D line
q_tasks (mp.Queue) – Queue from which get orders from the master.
options (Dict[str, Any]) – Additional options for frame computation.

Returns:

Pandas dataframe containing the data

Return type:

pd.DataFrame

Raises:

NotImplementedError – Function to override in the code interfaces

class scivianna.interface.generic_interface.Value1DAtLocation

Bases: GenericInterface

Interface parent class to implement a function to get 1D data at a specific location.

get_1D_value(position: Tuple[float, float, float], cell_index: str, material_name: str, field: str, options: Dict[str, Any] = None) → Series | List[Series]

Provides the 1D value of a field from either the (x, y, z) position, the cell index, or the material name.

Parameters:

position (Tuple[float, float, float]) – Position at which the value is requested
cell_index (str) – Index of the requested cell
material_name (str) – Name of the requested material
field (str) – Requested field name
options (Dict[str, Any], optional) – Additional options for 1D value computation.

Returns:

Field value

Return type:

Union[pd.Series, List[pd.Series]]

class scivianna.interface.generic_interface.ValueAtLocation

Bases: GenericInterface

Interface parent class to implement a function to get values at a specific location.

get_value(position: Tuple[float, float, float], cell_index: str, material_name: str, field: str, options: Dict[str, Any] = None) → str | float

Provides the result value of a field from either the (x, y, z) position, the cell index, or the material name.

Parameters:

position (Tuple[float, float, float]) – Position at which the value is requested
cell_index (str) – Index of the requested cell
material_name (str) – Name of the requested material
field (str) – Requested field name
options (Dict[str, Any], optional) – Additional options for value computation.

Returns:

Field value

Return type:

Union[str, float]

get_values(positions: List[Tuple[float, float, float]], cell_indexes: List[str], material_names: List[str], field: str, options: Dict[str, Any] = None) → List[str | float]

Provides the result values at different positions from either the (x, y, z) positions, the cell indexes, or the material names.

Parameters:

positions (List[Tuple[float, float, float]]) – List of position at which the value is requested
cell_indexes (List[str]) – Indexes of the requested cells
material_names (List[str]) – Names of the requested materials
field (str) – Requested field name
options (Dict[str, Any], optional) – Additional options for value computation.

Returns:

Field values

Return type:

List[Union[str, float]]

scivianna.interface package

Scivianna Interface Module

Files

Interface Hierarchy

GenericInterface (Base Class)

Data Capability Interfaces

Geometry2D Interface

Geometry2DPolygon Interface

Geometry2DGrid Interface

ValueAtLocation Interface

Value1DAtLocation Interface

OverLine Interface

CouplingInterface

Available Interfaces

MED Interface

VTK Interface

CSV Interface

Creating Custom Interfaces

Interface Registration

Submodules

scivianna.interface.csv_result module

scivianna.interface.generic_interface module

scivianna.interface.med_interface module

scivianna.interface.structured_mesh_interface module

scivianna.interface.time_dataframe module

scivianna.interface.vtk_interface module

Module contents