utils

io_utils

This module contains the functionality needed to save and load pywfe.Model objects

pywfe.utils.io_utils.load(folder, source='local')

Load a model from the path to its folder.

Parameters:
folderPath or str

The model to load.

sourcestr, optional

Where to load the model from. - If ‘database’, searches user database first, then falls back to package database. - If ‘local’, searches local directory first, then user database, then package database.

Returns:
modelpywfe.Model

The pywfe Model object.

Raises:
FileNotFoundError

Could not find the model folder.

pywfe.utils.io_utils.save(folder, model, source='local')

Saves the model. Only saves mesh information and description, not results.

Parameters:
folderpath or str

Folder to save the model to. Creates a folder or overwrites if it exists.

modelpywfe.Model

The model to save.

sourcestr, optional

Where to save the model. - If ‘local’, saves in the current working directory (./). - If ‘database’, saves in the user database (~/.pywfe/database/). - The default is ‘local’.

Returns:
None.
pywfe.utils.io_utils.database()

Lists all models in the database, printing user-saved models first, followed by the default package models. Each model is printed on a new line.

Returns:
None.

comsol_loader

This module contains the functionality needed to convert COMSOL data extracted from MATLAB LiveLink into a pywfe.Model class.

To extract the relevant matrices from COMSOL, use the following code after out = model;

MA = mphmatrix(model, 'sol1', 'out', {'K', 'D', 'E', 'L', 'Kc', 'Ec', 'Null', 'Nullf'});
info = mphxmeshinfo(model)

fid = fopen("mesh_info.json", 'w');
encodedJSON = jsonencode(info); 
fprintf(fid, encodedJSON); 
fclose('all'); 

writematrix(MA.K, 'K.txt', 'Delimiter', 'tab');
writematrix(MA.E, 'M.txt', 'Delimiter', 'tab');

writematrix(MA.Kc, 'Kc.txt', 'Delimiter', 'tab');
writematrix(MA.Ec, 'Mc.txt', 'Delimiter', 'tab');

writematrix(MA.Null, 'Null.txt', 'Delimiter', 'tab');
writematrix(MA.Nullf, 'Nullf.txt', 'Delimiter', 'tab');
pywfe.utils.comsol_loader.load_comsol(folder, axis=0, logging_level=20, solver='transfer_matrix')
Parameters:
folderstring

path to the folder containing the COMSOL LiveLink data.

axisint, optional

Waveguide axis. The default is 0.

logging_levelint, optional

Logging level. The default is 20 (info).

Returns:
modelpywfe.model class

a pywfe model.

pywfe.utils.comsol_loader.comsol_i2j(filename, skiprows=0)

Converts complex ‘j’ imaginary unit from COMSOL to python ‘j’

Parameters:
filenamestring

filename to convert.

skiprowsint, optional

see numpy loadtxt. The default is 1.

Returns:
None.

frequency_sweep

This module contains the fucntion for calculating various quantities over an array of frequencies for a pywfe.Model object.

pywfe.utils.frequency_sweep.frequency_sweep(model, f_arr, quantities, x_r=0, mac=False, dofs='all')

Perform a sweep over frequency array, extracting specified quantities at each step. Modal assurance criterion can be used to track modes through frequency by modeshape similarity.

Parameters:
modelpywfe.Model

The model to perform the sweep with.

f_arrnp.ndarray float

Frequency array.

quantitieslist of str

A list of strings specifying the quantities to be calculated. These are:

  • phi_plus: the (positive going) eigenvectors.

  • excited_amplitudes: see pywfe.Model.excited_amplitudes.

  • propagated_amplitudes: see pywfe.Model.propagated_amplitudes.

  • modal_displacements: see pywfe.Model.modal_displacements.

  • wavenumbers: see pywfe.Model.wavenumbers.

  • displacements: see pywfe.Model.displacements.

  • forces: see pywfe.Model.forces.

x_rfloat, np.ndarray, optional

Response distance(s). The default is 0.

macbool, optional

Use the modal assurance criterion to sort waves. The default is False.

dofsdofs, optional

The selected degrees of freedom. See pywfe.Model.dofs_to_inds. The default is ‘all’.

Returns:
outputdict

Dictionary of outputs for specified quantities.

pywfe.utils.modal_assurance.mac_matrix(modes_prev, modes_next)

Compute the Modal Assurance Criterion (MAC) matrix.

pywfe.utils.modal_assurance.sorting_indices(modes_prev, modes_next)
pywfe.utils.modal_assurance.sort_wavenumbers(wavenumbers, imag_threshold=None)

vtk tools

This module contains functions for sorting/returning data to be visualised in ParaView

pywfe.utils.vtk_tools.generate_coordinates(dof, x)

Generate multi-dimensional coordinates for nodes in a model based on an input x.

If x is iterable, each value in x is added to the first coordinate of the nodes, and other coordinates are repeated for each value in x.

If x is not iterable, it is simply added to the first coordinate of the nodes.

Parameters:
modelModelClass

The model object.

xint, float, or Iterable

The value(s) to be added to the first coordinate of the nodes.

Returns:
coordslist of numpy.ndarray

List of arrays of coordinates.

pywfe.utils.vtk_tools.sort_to_vtk(displacements, dof, vtk_fmt=True, fieldmap=None)

sorts a displacement array to a paraview-ready format.

Parameters:
displacementsnp.ndarray

field array.

dofTYPE

pywfe.Model.dict.dof dict.

vtk_fmtTYPE, optional

DESCRIPTION. The default is True.

fieldmapTYPE, optional

DESCRIPTION. The default is None.

Returns:
TYPE

DESCRIPTION.

pywfe.utils.vtk_tools.save_as_vtk(filename, field_array, x, dof, fieldmap=None)

Save data as a VTK file for visualization in ParaView.

This function generates a structured point cloud from the given degree-of-freedom (DOF) data and saves the provided field array in a format that can be visualized using VTK-compatible software like ParaView.

Parameters:
filenamestr

The name of the output VTK file (without the .vtk extension).

field_arraynp.ndarray

The numerical field values to be stored in the VTK file.

xfloat or array-like

The x-coordinate(s) where the field data is defined.

dofdict

Dictionary containing the model’s degrees of freedom (DOF) information.

fieldmapdict, optional

A dictionary mapping original field variable names to new names for improved readability in visualization. If None, the original field variable names are used. Default is None.

Returns:
None

The function writes a VTK file to disk but does not return a value.

Notes

  • This function internally calls generate_coordinates() to determine the spatial positions of the DOFs.

  • It uses sort_to_vtk() to transform the field data into a VTK-compatible format.

  • The output can be loaded directly into ParaView for further analysis.

  • If the model is 2D, the function adds a zero-valued third coordinate (zz = 0) to ensure compatibility with VTK.

Examples

Save a model’s displacement field as a VTK file:

`python save_as_vtk("output/displacement_field", displacements, x, model.dof) `

With a field variable mapping:

`python fieldmap = {"displacement_x": "Ux", "displacement_y": "Uy"} save_as_vtk("output/displacement_field", displacements, x, model.dof, fieldmap=fieldmap) `

pywfe.utils.vtk_tools.rotate_dofs(dofs, theta)

Rotates the 2D coordinates of the DOFs by angle theta.

Parameters: dofs (dict): Original DOFs dictionary with ‘coord’ key. theta (float): Angle in radians to rotate.

Returns: dict: New DOFs dictionary with rotated coordinates.