graphlow.base package

Submodules

graphlow.base.dict_tensor module

class graphlow.base.dict_tensor.GraphlowDictTensor(dict_tensor, length=None, *, time_series=False, device=-1, dtype=None)

Bases: object

Parameters:

• dict_tensor (GraphlowDictTensor | dict[KeyType, ArrayDataType])

• length (int | None)

• time_series (bool | list[bool])

• device (torch.device | int)

• dtype (torch.dtype | type | None)

convert_to_numpy_scipy()

Return type:

dict[str | Enum, ndarray | sparray]

property device: device

property dict_tensor: dict[str | Enum, GraphlowTensor]

property dtype: dtype

extract_by_rel_incidence(rel_incidence)

Extract data GraphlowDictTensor by the relative incidence matrix.

Parameters:

rel_incidence (torch.Tensor) – (n_other_data, n_self_data)-shaped sparse csr tensor.

Returns:

Extracted data.

Return type:

graphlow.GraphlowDictTensor

has_time_series()

Test if it has time series data.

Return type:

bool

items()

Return type:

ItemsView

keys()

Return type:

KeysView

pop(key)

Parameters:

key (str | Enum)

Return type:

GraphlowTensor

send(*, device=None, dtype=None)

Convert features to the specified device and dtype.

Parameters:

• device (torch.device | int | None)

• dtype (torch.dtype | type | None)

update(dict_tensor, *, time_series=False, overwrite=False)

Update GraphlowDictTensor with input dict.

Parameters:

• dict_data (dict | graphlow.GraphlowDictTensor)

• overwrite (bool) – If True, allow overwriting exsiting items. The default is False.

• dict_tensor (GraphlowDictTensor | dict[str | Enum, ndarray | sparray | Tensor])

• time_series (bool | list[bool])

validate_length_if_needed()

Validate graphlow tensors’ lengths.

values()

Return type:

ValuesView

graphlow.base.mesh module

class graphlow.base.mesh.GraphlowMesh(pvmesh, *, dict_point_tensor=None, dict_cell_tensor=None, dict_sparse_tensor=None, device=-1, dtype=None)

Bases: IReadOnlyGraphlowMesh

Parameters:

• pvmesh (pv.UnstructuredGrid)

• dict_point_tensor (GraphlowDictTensor | None)

• dict_cell_tensor (GraphlowDictTensor | None)

• dict_sparse_tensor (GraphlowDictTensor | None)

• device (torch.device | int)

• dtype (torch.dtype | type | None)

add_original_index()

Set original indices to points and cells. We do not use vtkOriginalPointIds and vtkOriginalCellIds because they are hidden.

compute_area_vecs()

Compute (n_elements, dims)-shaped area vectors.

Available celltypes are: VTK_TRIANGLE, VTK_QUAD, VTK_POLYGON

Return type:

torch.Tensor[float]

compute_areas(allow_negative_area=False)

Compute (n_elements,)-shaped areas.

Available celltypes are: VTK_TRIANGLE, VTK_QUAD, VTK_POLYGON

Parameters:

allow_negative_area (bool, optional [False])

Return type:

torch.Tensor[float]

compute_cell_adjacency(refresh_cache=False)

Compute (n_cells, n_cells)-shaped sparse adjacency matrix including self-loops. The method is cached.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_cell_degree(refresh_cache=False)

Compute (n_cells, n_cells)-shaped degree matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the degree matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_cell_point_incidence(refresh_cache=False)

Compute (n_cells, n_points)-shaped sparse incidence matrix. The method is cached.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the incidence matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_cell_relative_incidence(other_mesh, minimum_n_sharing=None)

Compute (n_cells_other, n_cells_self)-shaped sparse incidence matrix based on cells.

Parameters:

• other_mesh (graphlow.GraphlowMesh) – Other mesh object to be

• minimum_n_sharing (int | None) – Minimum number of sharing points to define connectivity. If not set, it will be the number of points for each cell.

Returns:

(n_cells_other, n_cells_self)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_facet_cell_incidence(refresh_cache=False)

Compute (n_facets, n_cells)-shaped sparse incidence matrix.

Parameters:

• cache (bool, optional [True]) – If True, the result is cached.

• refresh_cache (bool)

Returns:

(n_facets, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_isoAM(with_moment_matrix=True, consider_volume=False)

Compute (dims, n_points, n_points)-shaped isoAM.

Parameters:

• with_moment_matrix (bool, optional [True]) – If True, scale the matrix with moment matrices, which are tensor products of relative position tensors.

• consider_volume (bool, optional [False]) – If True, consider effective volume of each vertex.

Returns:

• isoAM (torch.Tensor | None) – (dims, n_points, n_points)-shaped sparse csr tensor

• Minv (torch.Tensor | None) –

  if with_moment_matrix is True,

  return (n_points, dims, dims)-shaped tensor

  if with_moment_matrix is False,

  return None

Return type:

tuple[Tensor, Tensor | None]

compute_isoAM_with_neumann(normal_weight=10.0, with_moment_matrix=True, consider_volume=False)

Compute (dims, n_points, n_points)-shaped Neumann boundary model IsoAM.

Parameters:

• normal_weight (float, optional [10.0]) – Weight of the normal vector.

• with_moment_matrix (bool, optional [True]) – If True, scale the matrix with moment matrices, which are tensor products of relative position tensors.

• consider_volume (bool, optional [False]) – If True, consider effective volume of each vertex.

Returns:

• NIsoAM (torch.Tensor) – (dims, n_points, n_points)-shaped sparse csr tensor

• weighted_normals (torch.Tensor) – (n_points, dims)-shaped tensor

• Minv (torch.Tensor | None) –

  if with_moment_matrix is True,

  return (n_points, dims, dims)-shaped tensor

  if with_moment_matrix is False,

  return None

Return type:

tuple[Tensor, Tensor, Tensor | None]

compute_median(data, mode='elemental', n_hop=1)

Perform median filter according with adjacency of the mesh.

Parameters:

• data (torch.Tensor) – data to be filtered.

• mode (str, "elemental", or "nodal", default: "elemental") – specify the mode of the data.

• n_hop (int, optional [1]) – The number of hops to make filtering.

Return type:

torch.Tensor

compute_normalized_cell_adjacency(refresh_cache=False)

Compute (n_cells, n_cells)-shaped normalized adjacency matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the normalized adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_normalized_point_adjacency(refresh_cache=False)

Compute (n_points, n_points)-shaped normalized adjacency matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the normalized adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_points, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_normals()

Compute (n_elements, dims)-shaped normals.

Available celltypes are: VTK_TRIANGLE, VTK_QUAD, VTK_POLYGON

Return type:

torch.Tensor[float]

compute_point_adjacency(refresh_cache=False)

Compute (n_points, n_points)-shaped sparse adjacency matrix including self-loops. The method is cached.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_points, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_point_degree(refresh_cache=False)

Compute (n_points, n_points)-shaped degree matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the degree matrix. Otherwise, return the cached result if available.

Returns:

(n_points, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_point_relative_incidence(other_mesh)

Compute (n_points_other, n_points_self)-shaped sparse incidence matrix based on points.

Parameters:

other_mesh (graphlow.GraphlowMesh) – Other mesh object to be

Returns:

(n_points_other, n_points_self)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

compute_volumes(allow_negative_volume=True)

Compute (n_elements,)-shaped volumes.

Available celltypes are: VTK_TETRA, VTK_PYRAMID, VTK_WEDGE, VTK_VOXEL, VTK_HEXAHEDRON, VTK_POLYHEDRON

Parameters:

allow_negative_volume (bool, optional [True]) – If True, compute the signed volume.

Return type:

torch.Tensor[float]

convert_elemental2nodal(elemental_data, mode='mean')

Convert elemental data to nodal data.

Parameters:

• elemental_data (torch.Tensor) – elemental data to convert.

• mode ("mean", or "effective", default: "mean") – The way to convert. - “mean”: averages the values of elements connected to each node. (default) - “effective”: distributes element information to the connected nodes, ensuring consistent volume.

Return type:

torch.Tensor

convert_nodal2elemental(nodal_data, mode='mean')

Convert nodal data to elemental data.

Parameters:

• nodal_data (torch.Tensor) – nodal data to convert.

• mode ("mean", or "effective", default: "mean") – The way to convert. - “mean”: averages the values of nodes connected to each element. (default) - “effective”: distributes node information to the connected elements, ensuring consistent volume.

Return type:

torch.Tensor

copy_features_from_pyvista(*, overwrite=False)

Copy point and cell data from pyvista mesh.

Parameters:

overwrite (bool) – If True, allow overwriting exsiting items. The default is False.

copy_features_to_pyvista(*, overwrite=False)

Copy point and cell tensor data to pyvista mesh.

Parameters:

overwrite (bool) – If True, allow overwriting exsiting items. The default is False.

property device: device

property dict_cell_tensor: GraphlowDictTensor

property dict_point_tensor: GraphlowDictTensor

property dict_sparse_tensor: GraphlowDictTensor

property dtype: dtype

extract_cells(ind, invert=False, add_original_index=True, pass_point_data=False, pass_cell_data=False)

Extract cells by indices.

Parameters:

• ind (sequence[int]) – Numpy array of cell indices to be extracted.

• invert (bool, optional [False]) – Invert the selection.

• add_original_index (bool, optional [True]) – If True, add original index feature to enable relative incidence matrix computation.

• pass_point_data (bool, optional [False]) – If True, the extracted mesh will inherit the dict_point_tensor from this mesh. This parameter is used, for example, when you want to differentiate the metrics of the extracted mesh based on the point information of this mesh.

• pass_cell_data (bool, optional [False]) – If True, the extracted mesh will inherit the dict_cell_data from this mesh. This parameter is used, for example, when you want to differentiate the metrics of the extracted mesh based on the cell information of this mesh.

Returns:

Extracted cells mesh.

Return type:

graphlow.GraphlowMesh

extract_facets(add_original_index=True, pass_point_data=False)

Extract all internal/external facets of the volume mesh with (n_faces, n_cells)-shaped sparse signed incidence matrix

Parameters:

• add_original_index (bool, optional [True]) – If True, add original index feature to enable relative incidence matrix computation.

• pass_point_data (bool, optional [False]) – If True, the extracted mesh will inherit the dict_point_tensor from this mesh. This parameter is used, for example, when you want to differentiate the metrics of the extracted mesh based on the point information of this mesh.

Returns:

facets – Extracted facets mesh.

Return type:

graphlow.GraphlowMesh

extract_surface(add_original_index=True, pass_point_data=False)

Extract surface.

Parameters:

• add_original_index (bool, optional [True]) – If True, add original index feature to enable relative incidence matrix computation.

• pass_point_data (bool, optional [False]) – If True, the extracted mesh will inherit the dict_point_tensor from this mesh. This parameter is used, for example, when you want to differentiate the metrics of the extracted mesh based on the point information of this mesh.

Returns:

Extracted surface mesh.

Return type:

graphlow.GraphlowMesh

property n_cells: int

property n_points: int

property points: Tensor

property pvmesh: UnstructuredGrid

save(file_name, *, binary=True, cast=True, remove_time=True, overwrite_features=False, overwrite_file=False)

Save mesh data. On writing, dict_point_tensor and dict_cell_tensor will be copied to pyvista mesh.

Parameters:

• file_name (pathlib.Path | str) – File name to be written. If the parent directory does not exist, it will be created.

• binary (bool) – If True, write binary file. The default is True.

• cast (bool) – If True, cast mesh if needed. The default is True.

• remove_time (bool) – If True, remove TimeValue field data.

• overwrite_features (bool) – If True, allow overwriting features. The default is False.

• overwrite_file (bool) – If True, allow overwriting the file. The default is False.

send(*, device=None, dtype=None)

Convert features to the specified device and dtype. It does not modify pyvista mesh.

Parameters:

• device (torch.device | int | None)

• dtype (torch.dtype | type | None)

update_pyvista_data(dict_tensor, pyvista_dataset, *, overwrite=False)

Update PyVista dataset with the specified GraphlowDictTensor.

Parameters:

• dict_tensor (graphlow.GraphlowDictTensor) – DataSet to update. Typically dict_point_tensor or dict_cell_tensor.

• pyvista_dataset (pyvista.DataSetAttributes) – DataSet to be updated. Typically point_data or cell_data.

• overwrite (bool) – If True, allow overwriting exsiting items. The default is False.

graphlow.base.mesh_interface module

class graphlow.base.mesh_interface.IReadOnlyGraphlowMesh

Bases: object

abstract compute_area_vecs()

Compute (n_elements, dims)-shaped area vectors.

Available celltypes are: VTK_TRIANGLE, VTK_QUAD, VTK_POLYGON

Return type:

torch.Tensor[float]

abstract compute_areas(allow_negative_area=False)

Compute (n_elements,)-shaped areas.

Available celltypes are: VTK_TRIANGLE, VTK_QUAD, VTK_POLYGON

Parameters:

allow_negative_area (bool, optional [False])

Return type:

torch.Tensor[float]

abstract compute_cell_adjacency(refresh_cache=False)

Compute (n_cells, n_cells)-shaped sparse adjacency matrix including self-loops. The method is cached.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_cell_degree(refresh_cache=False)

Compute (n_cells, n_cells)-shaped degree matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the degree matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_cell_point_incidence(refresh_cache=False)

Compute (n_cells, n_points)-shaped sparse incidence matrix. The method is cached.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the incidence matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_cell_relative_incidence(other_mesh, minimum_n_sharing=None)

Compute (n_cells_other, n_cells_self)-shaped sparse incidence matrix based on cells.

Parameters:

• other_mesh (graphlow.GraphlowMesh) – Other mesh object to be

• minimum_n_sharing (int | None) – Minimum number of sharing points to define connectivity. If not set, it will be the number of points for each cell.

Returns:

(n_cells_other, n_cells_self)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_facet_cell_incidence(cache=True)

Compute (n_facets, n_cells)-shaped sparse incidence matrix.

Parameters:

cache (bool, optional [True]) – If True, the result is cached.

Returns:

(n_facets, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_isoAM(with_moment_matrix=True, consider_volume=False)

Compute (dims, n_points, n_points)-shaped isoAM.

Parameters:

• with_moment_matrix (bool, optional [True]) – If True, scale the matrix with moment matrices, which are tensor products of relative position tensors.

• consider_volume (bool, optional [False]) – If True, consider effective volume of each vertex.

Returns:

• isoAM (torch.Tensor | None) – (dims, n_points, n_points)-shaped sparse csr tensor

• Minv (torch.Tensor | None) –

  if with_moment_matrix is True,

  return (n_points, dims, dims)-shaped tensor

  if with_moment_matrix is False,

  return None

Return type:

tuple[Tensor, Tensor | None]

abstract compute_isoAM_with_neumann(normal_weight=10.0, with_moment_matrix=True, consider_volume=False)

Compute (dims, n_points, n_points)-shaped Neumann boundary model IsoAM.

Parameters:

• normal_weight (float, optional [10.0]) – Weight of the normal vector.

• with_moment_matrix (bool, optional [True]) – If True, scale the matrix with moment matrices, which are tensor products of relative position tensors.

• consider_volume (bool, optional [False]) – If True, consider effective volume of each vertex.

Returns:

• NIsoAM (torch.Tensor) – (dims, n_points, n_points)-shaped sparse csr tensor

• weighted_normals (torch.Tensor) – (n_points, dims)-shaped tensor

• Minv (torch.Tensor | None) –

  if with_moment_matrix is True,

  return (n_points, dims, dims)-shaped tensor

  if with_moment_matrix is False,

  return None

Return type:

tuple[Tensor, Tensor, Tensor | None]

abstract compute_median(data, mode='elemental', n_hop=1)

Perform median filter according with adjacency of the mesh.

Parameters:

• data (torch.Tensor) – data to be filtered.

• mode (str, "elemental", or "nodal", default: "elemental") – specify the mode of the data.

• n_hop (int, optional [1]) – The number of hops to make filtering.

Return type:

torch.Tensor

abstract compute_normalized_cell_adjacency(refresh_cache=False)

Compute (n_cells, n_cells)-shaped normalized adjacency matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the normalized adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_cells, n_cells)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_normalized_point_adjacency(refresh_cache=False)

Compute (n_points, n_points)-shaped normalized adjacency matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the normalized adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_points, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_normals()

Compute (n_elements, dims)-shaped normals.

Available celltypes are: VTK_TRIANGLE, VTK_QUAD, VTK_POLYGON

Return type:

torch.Tensor[float]

abstract compute_point_adjacency(refresh_cache=False)

Compute (n_points, n_points)-shaped sparse adjacency matrix including self-loops. The method is cached.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the adjacency matrix. Otherwise, return the cached result if available.

Returns:

(n_points, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_point_degree(refresh_cache=False)

Compute (n_points, n_points)-shaped degree matrix.

Parameters:

refresh_cache (bool, optional [False]) – If True, recompute the degree matrix. Otherwise, return the cached result if available.

Returns:

(n_points, n_points)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_point_relative_incidence(other_mesh)

Compute (n_points_other, n_points_self)-shaped sparse incidence matrix based on points.

Parameters:

other_mesh (graphlow.GraphlowMesh) – Other mesh object to be

Returns:

(n_points_other, n_points_self)-shaped sparse csr tensor.

Return type:

torch.Tensor[float]

abstract compute_volumes(allow_negative_volume=True)

Compute (n_elements,)-shaped volumes.

Available celltypes are: VTK_TETRA, VTK_PYRAMID, VTK_WEDGE, VTK_VOXEL, VTK_HEXAHEDRON, VTK_POLYHEDRON

Parameters:

allow_negative_volume (bool, optional [True]) – If True, compute the signed volume.

Return type:

torch.Tensor[float]

abstract convert_elemental2nodal(elemental_data, mode='mean')

Convert elemental data to nodal data.

Parameters:

• elemental_data (torch.Tensor) – elemental data to convert.

• mode ("mean", or "effective", default: "mean") – The way to convert. - “mean”: averages the values of elements connected to each node. (default) - “effective”: distributes element information to the connected nodes, ensuring consistent volume.

Return type:

torch.Tensor

abstract convert_nodal2elemental(nodal_data, mode='mean')

Convert nodal data to elemental data.

Parameters:

• nodal_data (torch.Tensor) – nodal data to convert.

• mode ("mean", or "effective", default: "mean") – The way to convert. - “mean”: averages the values of nodes connected to each element. (default) - “effective”: distributes node information to the connected elements, ensuring consistent volume.

Return type:

torch.Tensor

abstract property device: device

abstract property dict_cell_tensor: GraphlowDictTensor

abstract property dict_point_tensor: GraphlowDictTensor

abstract property dict_sparse_tensor: GraphlowDictTensor

abstract property dtype: dtype

abstract extract_cells(ind, invert=False, add_original_index=True, pass_point_data=False, pass_cell_data=False)

Parameters:

• ind (Any)

• invert (bool)

• add_original_index (bool)

• pass_point_data (bool)

• pass_cell_data (bool)

Return type:

IReadOnlyGraphlowMesh

abstract extract_facets(add_original_index=True, pass_point_data=False)

Parameters:

• add_original_index (bool)

• pass_point_data (bool)

Return type:

IReadOnlyGraphlowMesh

abstract extract_surface(add_original_index=True, pass_point_data=False)

Parameters:

• add_original_index (bool)

• pass_point_data (bool)

Return type:

IReadOnlyGraphlowMesh

abstract property n_cells: int

abstract property n_points: int

abstract property points: Tensor

abstract property pvmesh: UnstructuredGrid

graphlow.base.tensor module

class graphlow.base.tensor.GraphlowTensor(tensor, *, time_series=False, device=-1, dtype=None)

Bases: object

Parameters:

• tensor (ArrayDataType)

• time_series (bool)

• device (torch.device | int)

• dtype (torch.dtype | type | None)

convert_to_numpy_scipy()

Return type:

ndarray | sparray

property device: device

property dtype: dtype

send(*, device=None, dtype=None)

Convert tensor to the specified device and dtype.

Parameters:

• device (torch.device | int)

• dtype (torch.dtype | type | None)

property shape: Size

property tensor: Tensor

property time_series: bool

graphlow.base.tensor_property module

class graphlow.base.tensor_property.GraphlowTensorProperty(device=-1, dtype=None)

Bases: object

Parameters:

• device (device | int)

• dtype (dtype | type | None)

DEFAULT_FLOAT_TYPE = torch.float32

property device: device

property dtype: dtype

Module contents