SciPy

pynibs.mesh package

Submodules

pynibs.mesh.mesh_struct module

The mesh_struct.py module provides classes and methods for handling and manipulating mesh structures in the context of neuroimaging and brain stimulation studies. It includes classes for handling tetrahedral meshes and regions of interest (ROIs).

The module includes the following classes:

  • TetrahedraLinear: This class represents a mesh consisting of linear tetrahedra. It provides methods for

calculating various quantities of interest (QOIs) in the mesh, interpolating data between nodes and elements, calculating the electric field and current density, and more.

  • Mesh: This class is a general mesh class to initialize default attributes and provides methods to fill default

values based on the approach, write the mesh data to an HDF5 file, and print the mesh information.

  • ROI: This class represents a region of interest (ROI) in the mesh. It provides methods to write the ROI data to

an HDF5 file and print the ROI information.

Each class and method in this module is documented with docstrings providing more detailed information about its purpose, parameters, and return values.

This module is primarily used for handling and visualizing data related to neuroimaging and brain stimulation studies.

class pynibs.mesh.mesh_struct.Mesh(mesh_name, subject_id, subject_folder)

Bases: object

” Mesh class to initialize default attributes.

fill_defaults(approach)

Initializes attributes for a headreco mesh.

Parameters:

approach (str) – ‘headreco’ ‘mri2mesh’ ‘charm’

print()

Print self information.

write_to_hdf5(fn_hdf5, check_file_exist=False, verbose=False)

Write this mesh’ attributes to .hdf5 file.

Parameters:

  • fn_hdf5 (str) –

  • check_file_exist (bool) – Check if provided filenames exist, warn if not.

  • verbose (bool) – Print self information

class pynibs.mesh.mesh_struct.ROI(subject_id, roi_name, mesh_name)

Bases: object

Region of interest class to initialize default attributes.

print()

Print self information.

write_to_hdf5(fn_hdf5, check_file_exist=False, verbose=False)

Write this mesh’ attributes to .hdf5 file.

Parameters:

  • fn_hdf5 (str) –

  • check_file_exist (bool) – Check if provided filenames exist, warn if not.

  • verbose (bool) – Print self information

class pynibs.mesh.mesh_struct.TetrahedraLinear(points, triangles, triangles_regions, tetrahedra, tetrahedra_regions)

Bases: object

Mesh, consisting of linear tetrahedra.

Parameters:

  • points (array of float [N_points x 3]) – Vertices of FE mesh

  • triangles (np.ndarray of int [N_tri x 3]) – Connectivity of points forming triangles

  • triangles_regions (np.ndarray of int [N_tri x 1]) – Region identifiers of triangles

  • tetrahedra (np.ndarray of int [N_tet x 4]) – Connectivity of points forming tetrahedra

  • tetrahedra_regions (np.ndarray of int [N_tet x 1]) – Region identifiers of tetrahedra

N_points

Number of vertices

Type:

int

N_tet

Number of tetrahedra

Type:

int

N_tri

Number of triangles

Type:

int

N_region

Number of regions

Type:

int

region

Region labels

Type:

np.ndarray of int

tetrahedra_volume

Volumes of tetrahedra

Type:

np.ndarray of float [N_tet x 1]

tetrahedra_center

Center of tetrahedra

Type:

np.ndarray of float [N_tet x 1]

triangles_center

Center of triangles

Type:

np.ndarray of float [N_tri x 1]

triangles_normal

Normal components of triangles pointing outwards

Type:

np.ndarray of float [N_tri x 3]

calc_E(grad_phi, omegaA)

Calculate electric field with gradient of electric potential and omega-scaled magnetic vector potential A.

\mathbf{E}=-\nabla\varphi-\omega\mathbf{A}

Parameters:

  • grad_phi (np.ndarray of float) – (N_tet, 3) Gradient of Scalar DOF in tetrahedra center.

  • omegaA (np.ndarray of float) – (N_tet, 3) Magnetic vector potential in tetrahedra center (scaled with angular frequency omega).

Returns:

E – (N_tet, 3) Electric field in tetrahedra center.

Return type:

np.ndarray of float

calc_E_normal_tangential_surface(E, fname)

Calculate normal and tangential component of electric field on given surfaces of mesh instance.

Parameters:

  • E (np.ndarray of float [N_tri x 3]) – Electric field data on surfaces

  • fname (str) – Filename of the .txt file containing the tetrahedra indices, which are adjacent to the surface triangles generated by the method “calc_surface_adjacent_tetrahedra_idx_list(self, fname)”

Returns:

  • En_pos (np.ndarray of float [N_tri x 3]) – Normal component of electric field of top side (outside) of surface

  • En_neg (np.ndarray of float [N_tri x 3]) – Normal component of electric field of bottom side (inside) of surface

  • n (np.ndarray of float [N_tri x 3]) – Normal vector

  • Et (np.ndarray of float [N_tri x 3]) – Tangential component of electric field lying in surface

  • t (np.ndarray of float [N_tri x 3]) – Tangential vector

calc_E_on_GM_WM_surface(E, roi)

Determines the normal and tangential component of the induced electric field on a GM-WM surface using nearest neighbour principle.

Parameters:

  • E (np.ndarray of float [N_tri x 3]) – Induced electric field given in the tetrahedra centre of the mesh instance

  • roi (pynibs.roi.RegionOfInterestSurface) – RegionOfInterestSurface object class instance

Returns:

  • E_normal (np.ndarray of float [N_points x 3]) – Normal vector of electric field on GM-WM surface

  • E_tangential (np.ndarray of float [N_points x 3]) – Tangential vector of electric field on GM-WM surface

calc_E_on_GM_WM_surface3(phi, dAdt, roi, verbose=True, mode='components')

Determines the normal and tangential component of the induced electric field on a GM-WM surface by recalculating phi and dA/dt in an epsilon environment around the GM/WM surface (upper and lower GM-WM surface).

Parameters:

  • phi (np.ndarray of float) – (N_nodes, 1) Scalar electric potential given in the nodes of the mesh.

  • dAdt (np.ndarray of float) – (N_nodes, 3) Magnetic vector potential given in the nodes of the mesh.

  • roi (pynibs.mesh.mesh_struct.ORI) – RegionOfInterestSurface object class instance.

  • verbose (bool) – Print information to stdout.

  • mode (str) – Select mode of output: - “components” : return x, y, and z component of tangential and normal components - “magnitude” : return magnitude of tangential and normal component (normal with sign for direction)

Returns:

  • E_normal (np.ndarray of float) – (N_nodes, 3) Normal vector of electric field on GM-WM surface.

  • E_tangential (np.ndarray of float) – (N_nodes, 3) Tangential vector of electric field on GM-WM surface.

calc_E_on_GM_WM_surface_simnibs(phi, dAdt, roi, subject, verbose=False, mesh_idx=0)

Determines the normal and tangential component of the induced electric field on a GM-WM surface by recalculating phi and dA/dt in an epsilon environment around the GM/WM surface (upper and lower GM-WM surface) or by using the Simnibs interpolation function.

Parameters:

  • phi (np.ndarray of float) – (N_nodes, 1) Scalar electric potential given in the nodes of the mesh.

  • dAdt (np.ndarray of float) – (N_nodes, 3) Magnetic vector potential given in the nodes of the mesh.

  • roi (pynibs.mesh.mesh_struct.ROI) – RegionOfInterestSurface object class instance.

  • subject (pynibs.subject.Subject) – Subject object loaded from .hdf5 file.

  • verbose (bool) – Print information to stdout.

  • mesh_idx (int) – Mesh index.

Returns:

  • E_normal (np.ndarray of float) – (N_points, 3) Normal vector of electric field on GM-WM surface.

  • E_tangential (np.ndarray of float) – (N_points, 3) Tangential vector of electric field on GM-WM surface.

calc_E_on_GM_WM_surface_simnibs_KW(phi, dAdt, roi, subject, verbose=False, mesh_idx=0)

Determines the normal and tangential component of the induced electric field on a GM-WM surface by recalculating phi and dA/dt in an epsilon environment around the GM/WM surface (upper and lower GM-WM surface) or by using the Simnibs interpolation function.

Parameters:

  • phi (np.ndarray of float) – (N_nodes, 1) Scalar electric potential given in the nodes of the mesh.

  • dAdt (np.ndarray of float) – (N_nodes, 1) Magnetic vector potential given in the nodes of the mesh.

  • roi (pynibs.mesh.mesh_struct.ROI) – RegionOfInterestSurface object class instance.

  • subject (pynibs.subject.Subject) – Subject object loaded from .hdf5 file.

  • verbose (bool) – Print information to stdout.

  • mesh_idx (int) – Mesh index.

Returns:

  • E_normal (np.ndarray of float) – (N_points, 3) Normal vector of electric field on GM-WM surface.

  • E_tangential (np.ndarray of float) – (N_points, 3) Tangential vector of electric field on GM-WM surface.

calc_J(E, sigma)

Calculate current density J. The conductivity sigma is a list of np.arrays containing conductivities of regions (scalar and/or tensor).

\mathbf{J} = [\sigma]\mathbf{E}

Parameters:

  • E (np.ndarray of float) – (N_tet, 3) Electric field in tetrahedra center.

  • sigma (list of np.ndarray of float) – [N_regions](3, 3) Conductivities of regions (scalar and/or tensor).

Returns:

E – (N_tet, 3) Electric field in tetrahedra center.

Return type:

np.ndarray of float

calc_QOI_in_points(qoi, points_out)

Calculate QOI_out in points_out using the mesh instance and the quantity of interest (QOI).

Parameters:

  • qoi (np.ndarray of float) – Quantity of interest in nodes of tetrahedra mesh instance

  • points_out (np.ndarray of float) – Point coordinates (x, y, z) where the qoi is going to be interpolated by linear basis functions

Returns:

qoi_out – Quantity of interest in points_out

Return type:

np.ndarray of float

calc_QOI_in_points_tet_idx(qoi, points_out, tet_idx)

Calculate QOI_out in points_out sitting in tet_idx using the mesh instance and the quantity of interest (QOI).

Parameters:

  • qoi (np.ndarray of float) – Quantity of interest in nodes of tetrahedra mesh instance

  • points_out (np.ndarray of float) – Point coordinates (x, y, z) where the qoi is going to be interpolated by linear basis functions

  • tet_idx (np.ndarray of int) – Element indices where the points_out are sitting

Returns:

qoi_out – Quantity of interest in points_out

Return type:

np.ndarray of float

calc_gradient(phi)

Calculate gradient of scalar DOF in tetrahedra center.

Parameters:

phi (np.ndarray of float [N_nodes]) – Scalar DOF the gradient is calculated for

Returns:

grad_phi – Gradient of Scalar DOF in tetrahedra center

Return type:

np.ndarray of float [N_tet x 3]

calc_surface_adjacent_tetrahedra_idx_list(fname)

Determine the indices of the tetrahedra touching the surfaces and save the indices into a .txt file specified with fname.

Parameters:

fname (str) – Filename of output .txt file.

Returns:

<File> – Element indices of the tetrahedra touching the surfaces (outer-most elements)

Return type:

.txt file

data_elements2nodes(data)

Transforms an data in tetrahedra into the nodes after Zienkiewicz et al. (1992) [1]. Can only transform volume data, i.e. needs the data in the surrounding tetrahedra to average it to the nodes. Will not work well for discontinuous fields (like E, if several tissues are used).

Parameters:

data (np.ndarray [N_elements x N_data]) – Data in tetrahedra

Returns:

data_nodes – Data in nodes

Return type:

np.ndarray [N_nodes x N_data]

Notes

[1]

Zienkiewicz, Olgierd Cecil, and Jian Zhong Zhu. “The superconvergent patch recovery and a posteriori error estimates. Part 1: The recovery technique.” International Journal for Numerical Methods in Engineering 33.7 (1992): 1331-1364.

data_nodes2elements(data)

Interpolate data given in the nodes to the tetrahedra center.

Parameters:

data (np.ndarray [N_nodes x N_data]) – Data in nodes

Returns:

data_elements – Data in elements

Return type:

np.ndarray [N_elements x N_data]

get_faces(tetrahedra_indexes=None)

Creates a list of nodes in each face and a list of faces in each tetrahedra.

Parameters:

tetrahedra_indexes (np.ndarray) – Indices of the tetrehedra where the faces are to be determined (default: all tetrahedra)

Returns:

  • faces (np.ndarray) – List of nodes in faces, in arbitrary order

  • th_faces (np.ndarray) – List of faces in each tetrahedra, starts at 0, order=((0, 2, 1), (0, 1, 3), (0, 3, 2), (1, 2, 3))

  • face_adjacency_list (np.ndarray) – List of tetrahedron adjacent to each face, filled with -1 if a face is in a single tetrahedron. Not in the normal element ordering, but only in the order the tetrahedra are presented

get_outside_faces(tetrahedra_indices=None)

Creates a list of nodes in each face that are in the outer volume.

Parameters:

tetrahedra_indices (np.ndarray) – Indices of the tetrehedra where the outer volume is to be determined (default: all tetrahedra)

Returns:

faces – List of nodes in faces in arbitrary order

Return type:

np.ndarray

pynibs.mesh.transformations module

pynibs.mesh.utils module

Table of Contents

Previous topic

pynibs.hdf5_io package

This Page

Edit page
  • © Copyright 2024, Konstantin Weise, Ole Numssen.
  • Created using Sphinx 6.2.1.