Mesh files

With the CLI and in Python, path is used as given (a relative path is relative to the working directory). If a relative path does not exist and the environment variable GYRE_MESH_DIR names a directory, the file is looked up there. With GYRE_MESH_RESTRICT=1 only bare file names inside GYRE_MESH_DIR are accepted; a service sets both for itself (see Meshes in a service).

The case digest covers the contents of the file, not its name: editing the file changes the digest, renaming it does not.

All elements are complete Lagrange elements (Mesh.SecondOrderIncomplete = 0) and all volume elements of a mesh have the same degree. Triangles, tetrahedra, prisms, pyramids and serendipity elements are refused. A 2-D mesh must lie in a plane $z = \text{const}$. Binary MSH files and other format versions are refused; save again with -format msh41 or -format msh22.

The Gyre NPZ format has no upper limit on the geometry degree; see its arrays below.

A damaged file is never read as a smaller or a non-periodic mesh: counts declared in the file are checked against its contents, and a section that is cut off or has lost its opening line is an error.

A run with solver.smoother: line records the first five keys as case.lines of its result (null if the mesh has no lines or another smoother is used). In Python, meshio.inspect_mesh(path, lines=True) returns the summary with lines, and meshio.line_summary(mesh) the lines of a mesh object. The summary a service keeps for a stored mesh, and inspect_mesh without the argument, do not contain lines.

• Names, never paths. A name matches ^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}\.(msh|npz)$ (lower-case extension, no directories). Any other name, in the URL or in mesh.params.path of a case (also when it arrives through overrides), is answered 422 InvalidMeshName, and nothing is opened or written.
• Validated on upload. The request body is the file. It is read by the same reader as on the command line before it enters the store; a file the reader refuses is answered 422 InvalidMesh with the reader’s message and is not stored. A mesh already stored under that name stays as it was. A valid upload replaces an existing mesh of the same name.
• A case names a stored mesh. POST /cases/validate, /jobs and /sessions answer 404 UnknownMesh (the hint names the PUT to make) if the mesh is not in the store, and 422 InvalidCase if discretization.boundaries does not match the boundary groups of the mesh.
• Replacing a mesh. The result cache of jobs is keyed on the contents of the mesh file, so a job on a replaced mesh is computed anew. A session reads its mesh when it starts and keeps running on it, and reports the digest of that moment, if the mesh is replaced or deleted afterwards. A job that is still queued when its mesh is deleted fails.
• Access. With GYRE_API_TOKEN set, every mesh route, GET included, requires the bearer token, like the rest of the API.

The variables belong to the service’s environment and are read at each request. A mesh that replaces one of the same name does not count against the number of meshes.

An .npz upload must pass two limits on the uncompressed size of its arrays: four times GYRE_MESH_MAX_BYTES, which the service checks, and GYRE_MESH_MAX_EXPANDED_BYTES (1 GiB by default), which the reader checks in every process, the service included. With an upload limit above 256 MiB the second one is the smaller unless it is raised as well.

All four values are positive integers in bytes (a count for GYRE_MESH_STORE_MAX_FILES). For GYRE_MESH_MAX_BYTES, GYRE_MESH_STORE_MAX_FILES and GYRE_MESH_STORE_MAX_BYTES any other value, zero included, is replaced by the default, so 0 does not switch uploads off. An invalid GYRE_MESH_MAX_EXPANDED_BYTES is an error instead: every read of an .npz file fails with GYRE_MESH_MAX_EXPANDED_BYTES must be a positive integer, got '…' (a 422 InvalidMesh for an upload).

The store is <data_dir>/meshes. While the service runs it sets GYRE_MESH_DIR to that directory and GYRE_MESH_RESTRICT=1 in its own environment; job workers, session processes and pipeline runs inherit both, and the previous values are restored at shutdown. With the restriction the reader accepts only a bare file name inside that directory, so the check holds in every process that could read a mesh, not only in the request handler. The request handler checks the name against the pattern before it touches the file system, and error messages name the mesh as the client named it, never a server directory.

An upload is received into a temporary file of the store’s directory, with the size limit enforced on the Content-Length header and again while the body arrives. It is validated there, one upload at a time, and moved to its name only if it is accepted. Leftovers of an upload that was interrupted by a crash are removed at the next start.

An application object that is used without its start-up phase has not set the two variables; it answers a case that names a stored mesh with 503 MeshStoreInactive instead of resolving it. The name check and the lookup in the store come first, so a name that is not a store name is still a 422 InvalidMeshName and a mesh that is not stored a 404 UnknownMesh.

A Gyre mesh stores, per element, the numbers of its $(p_g + 1)^d$ geometry nodes on a lattice indexed [i, j(, l)] along the reference directions, with the nodes at the Legendre–Gauss–Lobatto (LGL) points of degree $p_g$ and shared between neighbours. Gmsh stores each element as a list of nodes in its own order, at equally spaced points.

1. Ordering. A table maps the Gmsh node order of each element type to lattice positions. For a hexahedron the order is vertices, edge interiors, face interiors (each as a quadrilateral of degree $p_g - 2$ in the frame of the face’s vertices) and the volume interior, recursively. An element whose first two lattice directions (and the third, in 3-D) form a left-handed frame has its first two directions exchanged (reoriented_elements).
2. Node distribution. Along every lattice direction the equally spaced nodes are interpolated to the LGL points of the same degree. Up to degree 2 the two sets coincide and nothing is done.
3. Topological numbering. Lattice nodes are numbered from the mesh topology, not from their coordinates: a vertex by its node in the file; an edge node by the two vertices of its edge and its position counted from the vertex with the smaller number; a face node (3-D) by the four vertices of its face and its position in a frame fixed by the smallest vertex; interior nodes are private to their element. Two elements that share an edge or a face therefore share its nodes exactly, whatever their local axes, and nodes that merely coincide in space — the two sides of a slit, a periodic pair — stay distinct.
4. Boundary faces. A face that belongs to one element only is a boundary face and takes the physical group of the boundary element with the same vertices. An element listed several times (MSH 2.2 repeats it per physical group) is used once.
5. Periodicity. The $Periodic node pairs are treated as an equivalence of nodes, so that a corner node that is the slave of two periodic curves is identified consistently. Each node gets a periodic master; faces are matched through the masters.
6. Validation. All coordinates must be finite and the Jacobian determinant positive at every geometry node of every element; then faces are matched and each interior pair gets its relative orientation.

In an unstructured mesh two neighbours generally disagree about the direction, and in 3-D about the order, of the axes on their common face. The connectivity records for each interior face which index symmetry (reversal of either face axis, exchange of the two) maps its nodes onto the neighbour’s; the spatial operator applies it when it reads the neighbour’s trace. reoriented_face_pairs counts the pairs for which that map is not the identity. The verification study on imported meshes tests free-stream preservation, conservation and neighbour coupling on such meshes.

The $p_g + 1$ equally spaced nodes on an edge and the $p_g + 1$ LGL nodes both determine the same polynomial of degree $p_g$, so evaluating the Lagrange interpolant of the first set at the second changes the representation and not the curve: the geometry of the file is reproduced exactly, up to round-off. The interpolation acts along lattice lines, and on an edge or face it uses only the nodes of that edge or face. Two neighbours thus compute the same coordinates for a shared node; because the node is stored once, under its topological number, the mesh is watertight by construction, with no tolerance for merging nodes by distance.

An .npz file holds the arrays of a Gyre mesh. gyre mesh convert and gyre.meshio.save_mesh write it; a program that builds meshes can write it directly with numpy.savez.

The reader checks shapes, integer types, index ranges and unique group names, and then validates the mesh like a Gmsh mesh (finite coordinates, positive Jacobians, face matching). Elements must be right-handed and neighbours must share node numbers: the NPZ reader does not re-orient or renumber.

The archive is measured before any array is read: every member must be an .npy array without Python objects whose header describes exactly the bytes stored for it, and the members together must stay within the size limit (see Limits).