zkit.io.wfs_field

Reconstruct TDSEZ wavefunctions from B-spline coefficients using igakit.

TDSEZ writes the solution psi as B-spline coefficients (the IGA dof vector) into td/wfs_<input>.h5 via the PETSc HDF5 viewer. The file layout is:

/wavefunction

(n_snap, n_dof_x[, n_dof_y[, n_dof_z]], 2) [Re, Im]

/knots_x, /knots_y, /knots_z

(1-D) PetIGA compact knot vector

/knots_x.attrs: SplineDegree (int) nfuncs (int) number of basis functions on that axis LMin, LMax (float) domain bounds

The coefficients are stored in tensor (i, j, k) index order (NOT the PetIGA node-closure global dof order), so a simple reshape to (nx, ny, nz, 2) recovers the control points.

We rebuild the open knot vector PetIGA/igakit expect by appending one trailing copy of the last knot (PetIGA’s compact vector already has the right-end knot at multiplicity p, so only ONE extra copy is needed to reach the open multiplicity p+1). Then we evaluate the B-spline with igakit’s compiled evaluator igakit.igalib.bsp.Evaluate{1,2,3} (the high-level NURBS.evaluate() is broken in igakit 0.1.0 – it returns an empty array – but the compiled engine works perfectly).

zkit.io.wfs_field.reconstruct_wfs(path, step=0, npoints=200, axes=None)

Reconstruct the wavefunction on a spatial grid from td/wfs_*.h5.

Parameters:

  • path (str | Path) – Path to td/wfs_<input>.h5.

  • step (int) – Snapshot index into the leading (time) axis.

  • npoints (int) – Number of grid points per axis when axes is not given.

  • axes – Optional explicit coordinate grids (one per spatial axis). Each must

lie inside the knot span [kv[p], kv[-p-1]]. :type axes: list[array-like] | None

Returns:

dim, step, axes, psi (complex), Re, Im, abs2,

SplineDegree, nfuncs, knots (open knot vectors). :rtype: dict with keys

zkit.io.wfs_field.reconstruct_static_wfs(path, istate=0, npoints=200, axes=None)

Reconstruct a static eigenstate psi_<istate> from EigenData_*.h5.

TDSEZ’s static writer stores each converged eigenstate as a top-level dataset psi_<i> (the IGA dof/coefficient vector, written by PETSc’s HDF5 viewer, i.e. already in tensor/i,j,k coefficient order) plus a top-level knots_x[_y,_z] carrying the {SplineDegree, nfuncs, mult_start_end} attributes. This is the same information the propagation writer emits, just split per-state instead of stacked under wavefunction.

The reconstruction reuses the exact igakit B-spline engine PetIGA uses.

Parameters:

  • path (str | Path) – Path to static/EigenData_<input>.h5.

  • istate (int) – Index of the eigenstate (the <i> in psi_<i>).

  • npoints (int) – Grid points per axis when axes is None.

  • axes – Optional explicit coordinate grids (one per spatial axis), each inside

the knot span [open_kv[p], open_kv[nfuncs]]. :type axes: list[array-like] | None

Returns:

dim, istate, axes, psi, Re, Im, abs2, SplineDegree, nfuncs, knots.

Return type:

dict (same keys as reconstruct_wfs())

zkit.io.wfs_field.wfs_to_vtk(res, out_path, fmt=None)

Export an evaluated wavefunction (from reconstruct_wfs()) to a VTK file for ParaView.

Parameters:

  • res (dict) – Output of reconstruct_wfs().

  • out_path – Destination file. The extension chooses the format:

.vts -> VTK StructuredGrid (recommended, native regular grid), .vtu -> VTK UnstructuredGrid (polydata points + cells), .vtk -> legacy VTK StructuredGrid. If fmt is given it overrides the extension. :type out_path: str | Path :param fmt: Optional explicit format: "vts", "vtu" or "vtk". :type fmt: str | None :param The grid carries point data: :type The grid carries point data: psi_re, psi_im, psi_mag (|psi|), :param and psi_phase (arg psi). For 1D the y/z extents are collapsed to a: :param single layer so ParaView still reads it as a valid structured grid.: :param Requires pyvista (declared in the viz extra).:

zkit.io.wfs_field.compute_wfs_norm(path, step=0, nq=5)

Exact <psi|psi> via Gauss quadrature over the knot spans (igakit).

Reads the wavefunction + knot vectors from path and integrates |psi|^2 with a tensor-product Gauss rule mapped into every interior knot span, using igakit’s Evaluate{1,2,3} basis engine. The per-span Jacobian (span length) is folded into the weights, so the result is exact to the chosen Gauss order (nq=5 already gives ~1e-15 for smooth splines) and works for non-uniform knot vectors. This is machine-accurate, unlike the rectangular rule over a uniform plot grid.

Parameters:

  • path (str | Path) – Path to td/wfs_<input>.h5.

  • step (int) – Snapshot index.

  • nq (int) – Gauss points per knot span (default 5 -> exact for degree <= 9 splines).

Returns:

float

Return type:

the squared norm integral of |psi|^2 over the whole domain.