Skip to content

treams_rs.io

T-matrix files in the tmat.h5 layout, and Gmsh meshes of sphere clusters.

Mirrors treams.io. Install the optional treams-rs[io] extra for h5py.

  • save_hdf5 and load_hdf5 write and read spherical T-matrices, alone or as a parameter sweep, in the HDF5 layout tmat.h5: the matrices, the angular vacuum wavenumber, the mode labels modes/l, modes/m and modes/polarization, the expansion positions and the embedding medium.
  • mesh_spheres adds spheres to a Gmsh model, for solvers that need a volume mesh. It takes the gmsh.model object; install gmsh separately.
  • LENGTHS, INVLENGTHS and FREQUENCIES give the SI factor of each unit name, for example LENGTHS["nm"] == 1e-9 and FREQUENCIES["THz"] == 1e12.

MatrixSet

MatrixSet = TMatrix | Sequence[MatrixSet] | NDArray[np.object_]

A TMatrix or a rectangular sweep: nested sequences or an object array of them.

load_hdf5

load_hdf5(filename: str | Path | h5py.Group, lunit: str='nm') -> TMatrix | NDArray[np.object_]

Read one T-matrix or a parameter sweep from a tmat.h5 file.

Mirrors treams.io.load_hdf5. The frequency comes from the first of frequency, angular_frequency, vacuum_wavelength, vacuum_wavenumber and angular_vacuum_wavenumber, converted with its unit attribute. The file may list one set of modes or separate incident and scattered modes, and may use the treams key names chirality, pidx and index. A matrix over a subset of modes becomes a square matrix over the union of both mode sets, with zeros for the missing coefficients.

Args

  • filename: Path of an HDF5 file, or an open h5py.Group.
  • lunit: Length unit of the returned positions and of 1/k0, a key of LENGTHS.

Returns

One TMatrix for a file without sweep axes, otherwise an object array of TMatrix with the sweep shape.

Differences from treams

treams drops the stored positions when it joins the incident and scattered modes, and reads only chirality_parameter for the embedding chirality.

mesh_spheres

mesh_spheres(radii: ArrayLike, positions: ArrayLike, model: Any, meshsize: float | None=None, meshsize_boundary: float | None=None) -> Any

Add spheres, physical volume/surface groups and mesh sizes to a Gmsh model.

Mirrors treams.io.mesh_spheres. Each sphere gets one physical volume group and one physical surface group. Gmsh allocates every tag, so geometry already in the model stays usable. You initialize Gmsh, generate and write the mesh, and finalize Gmsh.

Args

  • radii: Sphere radii, shape (spheres,); positive.
  • positions: Sphere centres, shape (spheres, 3), in the unit of radii.
  • model: The Gmsh model to extend, usually gmsh.model.
  • meshsize: Mesh size at the points of the model; 0.2 times the largest radius by default.
  • meshsize_boundary: Mesh size on the sphere surfaces; meshsize by default.

Returns

model, extended.

Differences from treams

treams uses the sphere volume tags as surface tags, which picks the wrong surfaces in a model that already holds geometry. treams-rs reads the boundary surfaces of each sphere.

save_hdf5

save_hdf5(h5file: h5py.Group, tms: MatrixSet, name: str='', description: str='', keywords: str='', embedding_group: h5py.Group | str | None=None, embedding_name: str='', embedding_description: str='', embedding_keywords: str='', uuid: bytes | None=None, uuid_version: int=4, lunit: str='nm', *, scatterers: Mapping[str, Any] | Sequence[Mapping[str, Any]] | None=None, computation: Mapping[str, Any] | None=None) -> None

Write spherical T-matrices to an open HDF5 group in the tmat.h5 layout.

Mirrors treams.io.save_hdf5. Every matrix of a sweep shares the mode labels, the positions and the polarization convention; k0 and the embedding medium may vary. save_hdf5 checks every input and reads the mesh and reproducibility files before its first write, so an error leaves the group unchanged.

The file gets the attribute storage_format_version = "v1" only when it holds both scatterers and computation metadata, and the computation stores a mesh or lists semi-analytical in its keywords. treams writes the same marker under the same conditions and also requires the embedding medium at /embedding, which save_hdf5 always provides through a link. The marker names the layout; it does not mean that a T-matrix database accepts the file.

Args

  • h5file: Open, writable HDF5 group, for example an h5py.File.
  • tms: One TMatrix or a rectangular sweep: nested sequences or an object array of them. The sweep shape leads the shape of the tmatrix dataset.
  • name: Name attribute of the file; skipped when empty, like every text attribute.
  • description: Description attribute of the file.
  • keywords: Keywords attribute of the file, for example "czinfinity, mirrorxyz, passive, reciprocal".
  • embedding_group: Group, or group path, that receives the embedding medium; "embedding" by default. A link /embedding points to another group.
  • embedding_name: Name attribute of the embedding medium.
  • embedding_description: Description attribute of the embedding medium.
  • embedding_keywords: Keywords attribute of the embedding medium.
  • uuid: Bytes stored as the uuid dataset; a random version-4 UUID by default.
  • uuid_version: Version attribute of a given uuid.
  • lunit: Length unit of the positions, a key of LENGTHS; k0 is stored in its inverse.
  • scatterers: Scatterer metadata: one mapping, written to /scatterer, or a sequence, written to /scatterer_<i>. A mapping may hold name, description, keywords, material (relative_permittivity, relative_permeability, chirality and text entries), geometry (shape, unit and size datasets) and position.
  • computation: Metadata of the computation, written to /computation: name, description, keywords, method, software (the package versions by default), mesh (a file path, or a mapping of file name to content) and files (paths, or {"path": ..., "name": ...} mappings, of files that reproduce the computation).

Differences from treams

lunit comes before the keyword-only scatterers and computation; treams orders them scatterers, computation, lunit. Pass all three by keyword to run the same call in both. treams accepts only a sequence of matrices, and raises NameError for computation metadata without a mesh or the semi-analytical keyword. The file also stores the embedding chirality under both chirality and chirality_parameter, and the position index under position_index, pidx and index, so treams reads it.