Meshes of model documents (beta)¶
A planar or axisymmetric model document with regions can be meshed in this
version, and its named boundaries can be listed and checked. Nothing solves it yet: this is the geometry half of the
model path. 3D model documents and model documents on an imported mesh (mesh.file) are refused with
route.not_implemented.
The mesher is the separate program axmp-mesher (it runs gmsh). Where it does not run (a wheel installed without the
mesh extra, or without the X11/OpenGL libraries gmsh needs), axmp validate lists the unavailable finding
build.requires_mesher first, with the install hint, and the commands below refuse the document with it. A document without a
geometry (a reactor) or on an imported mesh needs no mesher.
A split rectangle¶
{
"schema": "axionmultiphysics.design/1", "name": "split_rect", "symmetry": "planar",
"parameters": {"L": 0.04, "H": 0.01},
"materials": {"slab": {"density": 998, "thermal": {"k_W_mK": 0.6, "cp_J_kgK": 4180}}},
"regions": [
{"name": "a", "shape": {"rect": {"x": [0, "L/2"], "y": [0, "H"]}}, "material": "slab"},
{"name": "b", "shape": {"rect": {"x": ["L/2", "L"], "y": [0, "H"]}}, "material": "slab"}],
"curves": [{"name": "mk_line", "path": {"segment": [["L/4", 0], ["L/4", "H"]]}}],
"boundaries": {"hot": {"of": "a", "where": {"x": 0}}, "cold": {"of": "b", "where": {"x": "L"}},
"interface": {"between": ["a", "b"]}, "mk": {"curve": "mk_line"}},
"physics": {"heat": {"type": "heat.transfer", "domains": ["a", "b"],
"boundary_conditions": {"hot": {"kind": "temperature", "T_K": 310}, "cold": {"kind": "temperature", "T_K": 290},
"remaining": {"kind": "insulation"}}}},
"outputs": {"Q_mk": {"kind": "flux", "of": "heat", "on": "mk"}},
"mesh": {"size": "H/8"}
}
axmp boundaries¶
axmp boundaries split_rect.json # a text table
axmp boundaries split_rect.json --json # the same as JSON
axmp boundaries split_rect.json --json --mesh -o run # also mesh into run/ and count the faces
It validates the document (with the mesher probe), runs the mesher's resolve pass, then the full check: the checks
that axmp validate can only defer because they need the geometry. They are the empty selections
(boundary.empty_selection), the partition rule of every physics (physics.boundary_uncovered,
physics.boundary_double, physics.boundary_interior, physics.boundary_outside_domain), the partial matches
(boundary.partial_match, a warning), and the outputs on resolved boundaries (output.boundary_not_in_domain,
output.force_on_interior, output.force_needs_stress_form). After it the report's deferred list is empty.
The JSON is the validation report with three keys added:
symmetry;boundaries: one row per boundary name withselector(as written),entities,measureandmeasure_units("m", the length),area_m2(the revolved area, axisymmetric only),bbox(exact, keyed by the coordinate names),point,adjacent(the region pairs,exteriorlast) andused_by: the conditions keyed by the boundary (physics, kind, and the part the physics takes: a key is taken where its boundary lies on the domain boundary of that physics) then the outputs on it;edges: every boundary edge, sorted by its point, withadjacent,type,bbox,point,measure,names(the boundaries that select it; empty for an edge no boundary names, which"remaining"covers) andaxis.
With --mesh every row and edge also has faces, its number of boundary elements on the mesh (with the document's
mesh.refinements). No master number or geometry-kernel tag appears anywhere.
With an error the command prints the report with ok false and the first error's fields at the top level, the table
included when the boundaries could be resolved (the hints send you to it), and exits with status 1.
axmp mesh¶
removes the mesh.msh, mesh_info.json and mesh_in.json of an earlier run in run/ before it does anything else, so no
refusal leaves an earlier mesh behind, then runs the same checks before it meshes. When one fails, no mesh is written;
if the check that failed needs the geometry, the mesher's resolve pass has left its mesh_in.json (with "resolve_only":
true), mesh_info.json and mesh_mesher.log in run/. When all pass it writes run/mesh_in.json (the mesher's
input), run/mesh.msh, run/mesh_info.json (which lists the atoms and their master numbers) and run/mesh_mesher.log.
It prints ok, name, symmetry, geometry_order, the three paths, boundaries (measure, measure_units and, for
an axisymmetric model, area_m2) and the warnings. A failed mesher run is mesh.generation_failed, with the mesher's
error in the message and the log's path in the hint. The geometry order is mesh.geometry_order, else the largest
order every physics takes (mesh.geometry_order_lowered warns when that is 1 for a curved model). axmp validate takes --mesher too, for its probe.
Python¶
import axionmultiphysics as axmp
d = axmp.load("split_rect.json")
table = d.boundaries() # the --json report; raises the first error
m = axmp.mesh(d, workdir="run") # MeshedModel; without workdir a temporary directory is used and removed
m.symmetry, m.geometry_order, m.regions # regions: {"a": {"area_m2": ...}, ...} ("volume_m3" too when axisymmetric)
m.boundaries # the table's rows, without face counts
im = m.instance("a") # a region or domain name, a list of names, or None for every region
im.attributes["hot"] # instance boundary attributes of a boundary: list[int], 1..n
im.remaining_attributes, im.axis_attributes
im.vertices(), im.elements(), im.boundary(), im.boundary_attributes(), im.element_attributes()
fp = im.face_points("mk", order=4) # points, weights and normals for a flux integral
face_points(name=None, *, order, attribute=None) takes exactly one of a boundary (or section) name and an instance
attribute, which is the way to the edges no boundary names and to the axis. It returns NumPy arrays faces (m,),
elements (m,), ref (m, q, 2), weights (m, q) (the face Jacobian is included, so they sum to the length), normals
(m, q, 2) and points (m, q, 2). The normals are outward on the boundary of the instance; on a section (a boundary
interior to the instance) they have the orientation of the selection: from A to B for between, outward from D for of,
the written direction of a curve marker turned by +90 degrees. section(name) gives the faces of an interior boundary with
their signs and length. The instance mesh owns its data: it works after the MeshedModel is gone. Misuse (an unknown name,
a boundary with no face on the instance, an attribute that is not on it, both or neither argument) is a ValueError; an
electromagnetic design given to Design.boundaries() or axmp.mesh is refused with a message and no code.
axmp.mesh meshes into its working directory every time and reads what that run wrote.
Handing a mesh to the engines¶
im.fluids_mesh() and im.chem_mesh(order=2) give an instance mesh to the fluids and chemistry engines
(m.fluids_mesh(domain=None) and m.chem_mesh(domain=None, order=2) are shorthands for m.instance(domain) followed by
the call). The engines take no document yet (nothing solves a model document in this version), so the conditions are
yours to write, on the instance's own attribute numbers: im.attributes[name], im.remaining_attributes and
im.axis_attributes. A master number is not a boundary attribute of the instance mesh, and both engine families refuse
one.
import numpy as np
import axionmultiphysics as axmp
from axionmultiphysics import fluids
# Plane Poiseuille flow through a channel of height H (a model document with a geometry and its named boundaries)
L, H, U, nu = 0.04, 0.01, 0.01, 1e-6
d = {"schema": "axionmultiphysics.design/1", "name": "channel", "symmetry": "planar",
"parameters": {"L": L, "H": H},
"materials": {"water": {"density": 998.2, "fluid": {"mu_Pa_s": 0.001}}},
"regions": [{"name": "channel", "shape": {"rect": {"x": [0, "L"], "y": [0, "H"]}}, "material": "water"}],
"boundaries": {"inlet": {"of": "channel", "where": {"x": 0}}, "outlet": {"of": "channel", "where": {"x": "L"}},
"walls": {"of": "channel", "except": ["inlet", "outlet"]}},
"physics": {"flow": {"type": "fluid.incompressible", "options": {"equation": "stokes", "viscous_form": "laplacian"},
"boundary_conditions": {"inlet": {"kind": "inlet", "velocity_m_s": ["6*0.01*y*(H-y)/H^2", 0]},
"outlet": {"kind": "outlet", "pressure_Pa": 0},
"walls": {"kind": "wall"}}}},
"mesh": {"size": "H/8"}}
m = axmp.mesh(d)
im = m.instance()
fm = im.fluids_mesh() # a fluids.Mesh: a copy of the instance mesh
bcs = [{"attribute": a, "kind": "dirichlet", "value": lambda x, y: (6 * U * y * (H - y) / H**2, 0.0)}
for a in im.attributes["inlet"]]
bcs += [{"attribute": a, "kind": "do_nothing"} for a in im.attributes["outlet"]]
bcs += [{"attribute": a, "kind": "dirichlet", "value": (0.0, 0.0)} for a in im.attributes["walls"]]
sol = fluids.solve_stokes(fm, nu, bcs=bcs, form="laplacian") # the Laplacian form admits the developed outflow
fluids_mesh() returns an axionmultiphysics.fluids.Mesh with the instance mesh's vertices, triangles, boundary segments
and boundary attributes in the same order, and its nodes when the mesh has them (Mesh.has_nodes: true at geometry order 2,
false at geometry order 1, where an advection-dominated heat solve may use supg=True). It is a copy and owns its data.
In a build without the fluids module (a wheel from PyPI, the sequential source build) it raises AxionMultiPhysicsError
with the code build.requires_fluids; the MPI source build has it.
chem_mesh(order) returns a chem.TriMesh for chem.CurrentDistribution. order is the field order of the current
distribution, 1 or 2; the mesh records the instance's geometry_order and its edge_nodes() are the P2 nodes that lie off
their chord (on the circle of an annulus, none on straight edges). A mesh that has nodes is never straightened: chem_mesh(1) on one,
CurrentDistribution(mesh, order=1) and CurrentDistribution(mesh, order=2, curved=False) on a mesh that records geometry
order 2 all raise a ValueError that names the remedy, as does chem.meshes.red_refine of a curved bridge mesh (refine the
mesh by a smaller mesh.size). A model whose physics
takes a P1 field has its geometry order lowered to 1 by the validation, so its instance mesh has no nodes.
import axionmultiphysics as axmp
from axionmultiphysics import chem
d = {"schema": "axionmultiphysics.design/1", "name": "cell", "symmetry": "planar",
"materials": {"bath": {"electrolyte": {"kappa_S_m": 1.0}}},
"regions": [{"name": "bulk", "shape": {"rect": {"x": [0, 0.01], "y": [0, 0.02]}}, "material": "bath"}],
"boundaries": {"anode": {"of": "bulk", "where": {"x": 0}}, "cathode": {"of": "bulk", "where": {"x": 0.01}}},
"reactions": {"electrode": {"plate": {"kind": "linear", "i0_A_m2": 10, "E_eq_V": 0.0}}},
"physics": {"cell": {"type": "electrochem.current_distribution", "options": {"kinetics": "secondary", "order": 2},
"boundary_conditions": {
"anode": {"kind": "electrode", "reactions": ["plate"], "phi_s_V": 0.05},
"cathode": {"kind": "electrode", "reactions": ["plate"], "phi_s_V": 0.0},
"remaining": {"kind": "insulation"}}}},
"mesh": {"size": 0.001}}
m = axmp.mesh(d)
im = m.instance()
cd = chem.CurrentDistribution(m.chem_mesh(), order=2)
cd.set_conductivity({a: 1.0 for a in im.region_attribute.values()})
cd.add_electrode("anode", im.attributes["anode"], primary=True, phi_s=0.05)
cd.add_electrode("cathode", im.attributes["cathode"], primary=True, phi_s=0.0)
print(cd.solve()["converged"]) # the other two sides are insulating by default
The potential of the parallel-plate cell is linear, so the current per metre of depth is kappa * dV * Hc / gap to
round-off. The tolerances of the engine tests that run through this bridge (the closed forms of Poiseuille flow, the
two-layer flow, Hagen-Poiseuille flow in a pipe, a heat slab and this cell) are recorded per processor model in
cpp/tests/data/model/u2/cases/, written by scripts/model_bridge_tolerances.py --record.
Orientation and the direction of markers¶
The orientation rules are in named boundaries. An arc
marker path is read counter-clockwise from its first angle to its second (the validation requires the first to be the
smaller), so its normal, the left of the tangent, points to the arc's centre. A rect path has no written order, so its
orientation is not yours to choose: use between or of for an oriented flux through a closed curve. A segment or
polyline runs as written.
Limits of this version¶
- A
contourwith an elliptical segment is refused at validation (model.shape_not_offered): usedisk,rect,polygon,unionanddifference. - 3D model documents and model documents on an imported mesh are refused with
route.not_implemented. - A
wherefilter on a straight edge is decided exactly (the segment is cut at the filter's bounds; an edge that only touches the box is not reported). On a curved edge it is decided by the edge's bounding box, and a curved edge whose box encloses the filter's box strictly in every coordinate is not reported as a partial match, so a curve that crosses such a box while another edge of the boundary is selected is not warned about. An empty selection still lists the candidates. axmp.meshraisesroute.not_implementedfor a 3D document (at/symmetry), a document on an imported mesh (at/mesh/file) and a document with no geometry (at/regions;axmp meshprints a note for the last).