FEM Broker — FEMData¶
Solver-agnostic snapshot returned by g.mesh.queries.get_fem_data(dim).
Native persistence¶
FEMData round-trips to a native model.h5 (the neutral zone)
without any solver in the loop:
fem = g.mesh.queries.get_fem_data(dim=3)
fem.to_h5("model.h5", model_name="Tower")
restored = FEMData.from_h5("model.h5") # integrity-checked load
to_h5(path, *, model_name="", apegmsh_version="", ndf=0) writes
the snapshot; from_h5(path, *, root="/") reads it back. root=
selects a non-root group when the neutral zone lives nested inside
a larger file (e.g. the two-zone canonical file written by the
bridge). The read is integrity-checked: a snapshot_id
mismatch between the written and re-derived content raises
MalformedH5Error.
The neutral zone is written at schema NEUTRAL_SCHEMA_VERSION
(defined in mesh/_femdata_h5_io.py); the OpenSees zone written by
the bridge carries its own SCHEMA_VERSION. Each zone has a
compatibility floor, NEUTRAL_SCHEMA_FLOOR and SCHEMA_FLOOR: a
reader opens every file from the floor up to its own version and
refuses anything older or newer
(ADR 0113).
This is the same neutral zone the session writes via
apeGmsh(save_to=...) / g.save() — see the
Session page. FEMData.from_h5
is also the entry point apeGmsh.from_h5 builds on for chain-phase
reassembly.
apeGmsh.mesh.FEMData ¶
FEMData — Solver-ready FEM mesh broker.¶
The main output of apeGmsh's meshing pipeline. Organized by what the engineer needs: Nodes and Elements — with selections, BCs, loads, and masses as sub-composites.
Top-level composites::
fem.nodes → NodeComposite (IDs, coords, nodal loads, masses, node constraints)
fem.elements → ElementComposite (per-type element groups, surface constraints, element loads)
fem.info → MeshInfo (mesh statistics)
fem.inspect → InspectComposite (introspection and summaries)
Construction::
fem = FEMData.from_gmsh(dim=3, session=g, ndf=3)
fem = FEMData.from_gmsh(session=g) # all dims
fem = FEMData.from_msh("bridge.msh", dim=2)
fem = FEMData(nodes=..., elements=..., info=...) # direct
Usage::
# Domain nodes — MeshSelection iterates as (node_id, xyz) pairs
for nid, xyz in fem.nodes.select():
ops.node(nid, *xyz)
# Supports
for nid in fem.nodes.select(pg="Base").ids:
ops.fix(nid, 1, 1, 1)
# Elements (iterate by type)
for group in fem.elements:
for eid, conn in group:
ops.element(group.type_name, eid, *conn, mat_tag)
# Elements (resolve to flat arrays — single type; .resolve() on the
# GroupResult that .result() returns)
ids, conn = fem.elements.select(label="col.web").result().resolve()
# Constraints
K = fem.nodes.constraints.Kind
for c in fem.nodes.constraints.pairs():
if c.kind == K.RIGID_BEAM:
ops.rigidLink("beam", c.master_node, c.slave_node)
MeshInfo ¶
Read-only summary of mesh statistics.
Accessed via fem.info.
Attributes¶
n_nodes : int n_elems : int bandwidth : int types : list[ElementTypeInfo] Element types present in the mesh.
Source code in src/apeGmsh/mesh/FEMData.py
summary ¶
One-line summary string.
Source code in src/apeGmsh/mesh/FEMData.py
NodeComposite ¶
NodeComposite(node_ids: ndarray, node_coords: ndarray, physical: PhysicalGroupSet, labels: LabelSet, constraints=None, loads=None, sp=None, masses=None, partitions: dict[int, dict] | None = None, part_node_map: dict | None = None, ndf: ndarray | None = None, module_label: ndarray | None = None, provenance: ndarray | None = None, gmsh_source: tuple[str, str] | None = None)
Access and query nodes from the FEM mesh.
Primary interface::
fem.nodes.select(pg="Base") → MeshSelection (iterates (id, xyz));
.result() → NodeResult, .ids, .coords
fem.nodes.select() → all domain nodes
Sub-composites::
fem.nodes.constraints → NodeConstraintSet
fem.nodes.loads → NodalLoadSet
fem.nodes.masses → MassSet
Public properties for raw array access::
fem.nodes.ids → ndarray(N,) object dtype
fem.nodes.coords → ndarray(N, 3) float64
Source code in src/apeGmsh/mesh/FEMData.py
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 | |
module_label
property
¶
Per-node compose labels aligned 1:1 with :attr:ids.
Object ndarray of source-module labels (empty string for
host-owned rows), populated by the g.compose merge engine
(ADR 0038 §"Schema"). None when the broker carries no
module-label metadata (the uncomposed case). Read-only view
of the underlying array; consumers must not mutate it.
provenance
property
¶
Per-node provenance aligned 1:1 with :attr:ids (ADR 0049).
int8 array where PROVENANCE_MESH (0) marks an ordinary
Gmsh-vertex node and PROVENANCE_DECOUPLED (1) marks an
auxiliary node declared via g.decouple_node(...). None
when the broker carries no decoupled nodes (the common case).
Read-only view; consumers must not mutate it.
decoupled_ids
property
¶
Node IDs whose provenance is decoupled (ADR 0049).
Empty ndarray when the broker carries no decoupled nodes.
partitions
property
¶
Sorted list of partition IDs (empty if not partitioned).
select ¶
select(target=None, *, pg=None, label=None, tag=None, partition: int | None = None, dim: int | None = None, ids=None)
Select a subset of nodes from this FEM snapshot.
Returns a :class:~apeGmsh.mesh._mesh_selection.MeshSelection
(point family — .in_box tests node coordinates) that
chains spatial-refinement verbs and terminates at .ids /
.coords / .result()::
# seed by PG, read bulk arrays directly
base = fem.nodes.select(pg="Base")
base.ids # list[int]
base.coords # ndarray (N, 3)
# chain verbs, then drive a loop or feed ops
for nid, xyz in fem.nodes.select(pg="Base").result():
ops.node(nid, *xyz)
# spatial narrowing
corner = (fem.nodes.select(pg="Body")
.in_box((0, 0, 0), (1, 1, 1))
.on_plane((0, 0, 0), (0, 0, 1), tol=1e-6))
# set algebra
all_bcs = (fem.nodes.select(pg="Base")
| fem.nodes.select(pg="Wall"))
No arguments seeds every domain node.
.. note::
Point family — .in_box tests node coordinates
against a half-open box [lo, hi) (pass
inclusive=True for the closed box). For
geometry-level selection use :meth:g.model.select.
Parameters¶
target :
Label name, physical group name, part name,
(dim, tag) pair, raw int tag, or a list thereof.
A string resolves through label → PG → part name in
that order. A (dim, tag) pair is looked up in live
Gmsh, so it resolves only while the model this snapshot
was extracted from is the current Gmsh model, and raises
RuntimeError otherwise.
pg :
Physical group name or list of names.
label :
Geometry-time label name or list. Labels survive
boolean operations.
tag :
Raw physical group tag (int or list).
partition :
Restrict to nodes that belong to this partition number.
dim :
Restrict to nodes on entities of this topological
dimension (0=point, 1=curve, 2=surface, 3=volume).
ids :
Explicit node id list. When given, all other
selectors are ignored.
Refining verbs¶
Each returns a new MeshSelection and composes freely:
.in_box(lo, hi, *, inclusive=False)— half-open[lo, hi)by default;inclusive=Truefor[lo, hi]..in_sphere(center, radius).on_plane(point, normal, *, tol)—tol=is required; raisesTypeErrorif omitted..nearest_to(point, *, count=1).where(predicate)— callablexyz → bool.|&-^(set algebra).
Terminals¶
.ids—list[int]of selected node IDs..coords—ndarray (N, 3)of coordinates..result()→ :class:~apeGmsh._kernel.payloads.NodeResult; iterate as(nid, xyz)pairs, read.ids/.coordsarrays, or call.to_dataframe().
Source code in src/apeGmsh/mesh/FEMData.py
417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 | |
index ¶
Array index for a node ID. O(1) after first call.
Source code in src/apeGmsh/mesh/FEMData.py
ndf_for ¶
Return the per-node ndf (DOF count) for nid, if stored.
Per-node ndf is inferred by the apeSees bridge from
the incident element classes (ADR 0048); an element-less
decoupled node states it explicitly with ops.ndf(handle,
ndf=K) (ADR 0049). This accessor only returns a value when
such metadata was attached to the snapshot; the broker does not
infer ndf on its own.
Raises¶
KeyError
If nid is not a known node ID.
LookupError
If nid exists but the snapshot carries no ndf for it —
the bridge infers it from elements (or, for an element-less
node, ops.ndf(handle, ndf=K)).
Source code in src/apeGmsh/mesh/FEMData.py
ElementComposite ¶
ElementComposite(groups: dict[int, ElementGroup], physical: PhysicalGroupSet, labels: LabelSet, constraints=None, loads=None, partitions: dict[int, dict] | None = None, part_elem_map: dict | None = None, module_label: dict[int, ndarray] | None = None, reinforce_ties=None, embed_ties=None, contacts=None, contact_planes=None, rebar_elements=None, interfaces=None, gmsh_source: tuple[str, str] | None = None, entity: dict[int, ndarray] | None = None)
Access and query elements from the FEM mesh.
Iterable — yields ElementGroup objects::
for group in fem.elements:
print(group.type_name, len(group))
Selection API::
result = fem.elements.select(label="col.web").result()
ids, conn = result.resolve() # single-type
ids, conn = result.resolve(element_type='tet4') # pick one
Sub-composites::
fem.elements.constraints → SurfaceConstraintSet
fem.elements.loads → ElementLoadSet
Source code in src/apeGmsh/mesh/FEMData.py
853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 | |
connectivity
property
¶
Flat connectivity — only if all elements are the same type.
Raises¶
TypeError If multiple element types are present.
module_label
property
¶
Per-element compose labels keyed by element-type code.
Each value is an object ndarray aligned 1:1 with that type's
group ids (empty string for host-owned rows), populated by
the g.compose merge engine (ADR 0038 §"Schema"). None
when the broker carries no module-label metadata (the
uncomposed case). Read-only view; consumers must not mutate.
entity
property
¶
Per-element source entity keyed by element-type code.
Each value is an (E_t,) int32 array aligned 1:1 with that
type's group ids: the tag of the Gmsh model entity of the
type's own dimension the element is classified on, a partition
entity resolved to its parent, -1 unknown. Raw
tags: entity tags repeat across composed modules, so a member
is keyed by (module_label, entity). None when the
snapshot carries no stream. Read-only view; consumers must not
mutate.
module_label_by_id ¶
Flat element-id -> compose label map across all types.
Concatenates the per-type :attr:module_label arrays against
each type's ids. None when no module-label metadata is
carried (the uncomposed case). Used by the split-emit path to
bucket each element into its owning module fragment.
Source code in src/apeGmsh/mesh/FEMData.py
source_entity ¶
(labels, entity) for element ids eids of dimension dim.
Vectorised over the groups whose element dimension is dim:
labels is an object array of compose labels ("" for
host-owned rows), entity an int32 array of source-entity
tags (-1 unknown, and every row -1 when the snapshot
carries no stream), both aligned with eids. Together they
are the member key (module_label, entity).
Raises¶
KeyError
If an id is not an element of dimension dim.
Source code in src/apeGmsh/mesh/FEMData.py
type_table ¶
DataFrame of element types in the mesh.
Source code in src/apeGmsh/mesh/FEMData.py
select ¶
select(target=None, *, pg=None, label=None, tag=None, dim: int | None = None, element_type: str | int | None = None, partition: int | None = None, ids=None)
Select a subset of elements from this FEM snapshot.
Returns a :class:~apeGmsh.mesh._mesh_selection.MeshSelection
(point family — spatial verbs test element centroids) that
chains spatial-refinement verbs and terminates at .ids /
.connectivity / .result()::
# seed by PG, read element ids
body = fem.elements.select(pg="Body")
body.ids # list[int]
body.connectivity # ndarray (N, npe) — homogeneous mesh only
# filter to one element type in a spatial region
tets = (fem.elements.select(pg="Body", element_type="tet4")
.in_box((0, 0, 0), (5, 5, 3)))
# mixed mesh — call .resolve() on the GroupResult
gr = fem.elements.select(label="col.web").result()
ids, conn = gr.resolve() # single type
ids, conn = gr.resolve(element_type="hex8") # pick from mixed
No arguments seeds every element.
.. note::
Point family — .in_box tests element centroids
against a half-open box [lo, hi) (pass
inclusive=True for the closed box). For
geometry-level selection use :meth:g.model.select.
Parameters¶
target :
Label name, physical group name, part name,
(dim, tag) pair, raw int tag, or a list thereof.
A string resolves through label → PG → part name in
that order. A (dim, tag) pair is looked up in live
Gmsh, so it resolves only while the model this snapshot
was extracted from is the current Gmsh model, and raises
RuntimeError otherwise.
pg :
Physical group name or list of names.
label :
Geometry-time label name or list. Labels survive
boolean operations.
tag :
Raw physical group tag (int or list).
dim :
Restrict to elements of this topological dimension
(1=line, 2=surface, 3=volume).
element_type :
Restrict to a specific element type by name (e.g.
"tet4", "hex8") or Gmsh type code (int).
partition :
Restrict to elements belonging to this partition
number.
ids :
Explicit element id list. When given, all other
selectors are ignored.
Refining verbs¶
Each returns a new MeshSelection and composes freely
(spatial verbs test element centroids):
.in_box(lo, hi, *, inclusive=False)— half-open[lo, hi)by default;inclusive=Truefor[lo, hi]..in_sphere(center, radius).on_plane(point, normal, *, tol)—tol=is required; raisesTypeErrorif omitted..nearest_to(point, *, count=1).where(predicate)— callablecentroid_xyz → bool.|&-^(set algebra).
Terminals¶
.ids—list[int]of selected element IDs..coords—ndarray (N, 3)of element centroids..connectivity—ndarrayconnectivity; homogeneous selections only (raisesTypeErroron mixed element types)..groups()/.result()→ :class:~apeGmsh._kernel.payloads.GroupResult. Call.resolve()on theGroupResultto get(ids, connectivity); passelement_type=to pick one type from a mixed selection.
Source code in src/apeGmsh/mesh/FEMData.py
1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 | |
index ¶
Array index for an element ID. O(1) after first call.
Source code in src/apeGmsh/mesh/FEMData.py
InspectComposite ¶
Introspection and summary methods.
Accessed via fem.inspect.
Source code in src/apeGmsh/mesh/FEMData.py
summary ¶
One-line mesh summary plus sub-composite counts.
Source code in src/apeGmsh/mesh/FEMData.py
node_table ¶
DataFrame of all nodes.
Source code in src/apeGmsh/mesh/FEMData.py
element_table ¶
DataFrame of all elements with a type column.
Source code in src/apeGmsh/mesh/FEMData.py
constraint_summary ¶
Human-readable breakdown of all constraints.
Source code in src/apeGmsh/mesh/FEMData.py
load_summary ¶
Human-readable breakdown of all loads.
Source code in src/apeGmsh/mesh/FEMData.py
mass_summary ¶
Human-readable breakdown of masses.
Source code in src/apeGmsh/mesh/FEMData.py
find_coincident_node_pairs ¶
find_coincident_node_pairs(*, tol: float = 1e-06, pg: str | None = None) -> dict[tuple[int, int], list[str]]
Find distinct nodes that share an XYZ within tolerance.
Opt-in diagnostic for suspect topology — most commonly the arc-line junction case, where OCC builds an arc-bounded wire without welding the arc endpoints onto the joining line's point tags. The mesh then carries two distinct nodes at every junction with no element or constraint bridging them.
Returns a dict mapping each coincident pair
(tag_a, tag_b) — sorted so tag_a < tag_b — to a list
of references that touch the pair:
"element <type>#<eid>"— both nodes appear in the same element's connectivity (legitimate forzeroLength, tied interfaces, etc.)"constraint <kind>"— equalDOF / rigidLink / diaphragm / kinematic / node_to_surface bridges the pair
An empty list is the smoking gun: the pair is coincident
but nothing references them together — i.e. an unbridged
duplicate (the cimbra arc-line corner). An entry with only
constraint refs means the user has explicitly tied the
pair; an entry with an element zeroLength* ref is the
canonical legitimate case.
Parameters¶
tol : float
Maximum Euclidean distance between two nodes to consider
them coincident. Default 1e-6. Single value — if
you need per-constraint-type tolerances (each constraint
kind has its own physical tol), drive the resolver's
preflight directly instead.
pg : str | None
If given, restrict the scan to nodes belonging to this
physical group. Otherwise scan all domain nodes.
Returns¶
dict[tuple[int, int], list[str]]
{(tag_a, tag_b): [ref, ...]} for every coincident
pair. Empty dict if no coincident pairs are found.
Warnings¶
Builds a full-model KDTree on each call (SciPy cKDTree,
with a NumPy O(N²) fallback if SciPy is unavailable). Avoid
invoking inside tight loops on million-node models — cache
the result yourself if you need it repeatedly.
Examples¶
::
pairs = fem.inspect.find_coincident_node_pairs(tol=1e-6)
for (a, b), refs in pairs.items():
if not refs:
print(f"UNBRIDGED coincident pair: {a}, {b}")
else:
print(f"Pair {a},{b} bridged by: {refs}")
Source code in src/apeGmsh/mesh/FEMData.py
1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 | |
FEMData ¶
FEMData(nodes: NodeComposite, elements: ElementComposite, info: MeshInfo, mesh_selection: 'MeshSelectionStore | None' = None, composed_from: 'ComposeSet | tuple[ComposeRecord, ...] | None' = None, session_id: str | None = None, model_name: str = '', units: 'Any' = None)
Solver-ready FEM mesh broker.
Organized by what the user needs::
fem.nodes → NodeComposite
fem.elements → ElementComposite
fem.info → MeshInfo
fem.inspect → InspectComposite
Source code in src/apeGmsh/mesh/FEMData.py
1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 | |
units
property
writable
¶
Declared consistent unit system ID (e.g. "kN_m_s"), or None.
snapshot_id
property
¶
Deterministic content hash identifying this FEMData snapshot.
Computed once and cached. Used by the Results module to bind
result files to their producing geometry — see
internal_docs/Results_architecture.md § "FEMData embedding
& binding".
from_gmsh
classmethod
¶
Extract FEMData from a live Gmsh session.
Parameters¶
dim : int or None
Element dimension to extract. None = all dims.
session : apeGmsh session, optional
When provided, auto-resolves constraints, loads, masses.
ndf : int
DOFs per node for load/mass vector padding.
remove_orphans : bool
If True, remove mesh nodes not connected to any element.
The snapshot takes the session's session_id (h5-schema.md,
"Who mints it"): the session owns one uuid4 from begin(), so
every extraction of one session, and the geometry sibling it
writes, carry the same id. Without a session the snapshot mints
its own.
Source code in src/apeGmsh/mesh/FEMData.py
from_msh
classmethod
¶
Load FEMData from an external .msh file.
Source code in src/apeGmsh/mesh/FEMData.py
from_h5
classmethod
¶
Load a :class:FEMData snapshot from a root-layout model.h5.
Inverse of :meth:to_h5. Reads the seven neutral-zone groups
plus /meta and rebuilds nodes, elements (per type),
physical groups, labels, mesh selections, constraints, loads,
and masses — everything the writer round-trips.
Parameters¶
path : str
Path to a model.h5 written by :meth:to_h5, g.save(),
or apeSees(fem).h5(path).
root : str, default "/"
Sub-group root inside path to read from. Default
rehydrates from the file root (standalone model.h5
shape). Per ADR 0020 (Phase 4 cleanup), composed
results.h5 files carry the same rich layout under
/model/; pass root="/model" to rehydrate from a
composed file. Backcompat: root="/" produces
byte-identical behaviour to the pre-refactor reader.
Use this to resume a session-saved model in a later script::
# script 1 — build & save
with apeGmsh(model_name="m", save_to="m.h5") as g:
...
# script 2 — analyse
fem = FEMData.from_h5("m.h5")
apeSees(fem).h5("m.h5") # enrich with /opensees/...
Source code in src/apeGmsh/mesh/FEMData.py
to_native_h5 ¶
Embed this FEMData into an open HDF5 group (/model/).
Used by NativeWriter to snapshot the geometry alongside
results. The reconstructed FEMData (via from_native_h5)
will produce the same snapshot_id — this is the linking
contract for Results.bind().
Phase 4 cleanup (ADR 0020): writes the rich neutral-zone
layout :func:write_fem_h5 produces at the file root, but
under group instead. The composed results.h5 thus
carries /model/meta, /model/nodes, /model/elements,
etc. — the same layout :func:read_fem_h5(path, root="/model")
rehydrates from. This eliminates the /opensees_archive/
zone that the previous lean embedding required to round-trip
the full :class:OpenSeesModel.
Source code in src/apeGmsh/mesh/FEMData.py
to_h5 ¶
Write a fresh model.h5 containing the neutral zone.
Phase 8.5 entry point: dumps everything the broker knows about
the model (nodes, elements per type, physical groups, labels,
constraints, loads, masses) into a root-level
model.h5. No /opensees/ content is emitted — absent
enrichment is the right "no solver loaded" signal.
Use apeSees(fem).h5(path) instead to get a fully enriched
file (neutral zone + /opensees/...).
model_name defaults to the snapshot's own :attr:model_name
(P1, #1307), so a session-named snapshot round-trips its name
through /meta/model_name without the caller repeating it.
Source code in src/apeGmsh/mesh/FEMData.py
from_native_h5
classmethod
¶
Reconstruct a FEMData from its embedded /model/ group.
Phase 4 cleanup (ADR 0020): production writers (:meth:to_native_h5
via :class:NativeWriter) embed the rich neutral zone — full
constraints, loads, masses, mesh selections and partitions
round-trip alongside nodes/elements/PGs. snapshot_id of
the rebuilt FEM matches the source's /meta/snapshot_id
attribute (the linking contract :class:Results.bind relies
on).
Source code in src/apeGmsh/mesh/FEMData.py
from_mpco_model
classmethod
¶
Synthesize a partial FEMData from an MPCO MODEL/ group.
Carries: nodes, elements (per OpenSees class tag), physical
groups derived from MPCO Regions (MODEL/SETS).
Missing vs. native:
- apeGmsh-specific labels
- Pre-mesh declarations (loads / masses / constraints)
- STKO named selection sets (those live in .cdata sidecars)
- Gmsh-style element type codes (uses negated class_tag instead)
snapshot_id will not match a native FEMData of the same
mesh — that's expected. Results.bind() will refuse such
mismatches.
Source code in src/apeGmsh/mesh/FEMData.py
from_ladruno_model
classmethod
¶
Synthesize a partial FEMData from a .ladruno MODEL/ group.
Sibling of :meth:from_mpco_model for the self-describing
.ladruno layout (element groups carry a CONNECTIVITY
dataset + BASIS attrs). Carries nodes, elements (per OpenSees
class tag), and physical groups from MODEL/SETS. Missing vs.
native: apeGmsh labels, pre-mesh declarations, selection-set
names. snapshot_id will not match a native FEMData of the
same mesh — expected.
Source code in src/apeGmsh/mesh/FEMData.py
with_units ¶
Return a shallow copy with units set to the canonical unit system ID.
Source code in src/apeGmsh/mesh/FEMData.py
repartition ¶
Return a copy split into n_parts MPI ranks as one graph (ADR 0120 D2).
Every element of the snapshot is assigned, whatever module or
instance it came from, by recursive coordinate bisection of the
element centroids, balanced on the element weights (the node
count by default; weights maps an element type name such as
"hex8" to a weight, or is a callable
f(type_name, ids, centroids) returning one per element). A
rank holds the nodes of its elements, so a node on a cut is in
several ranks; a node no element references is in none, and the
OpenSees bridge routes it to the rank of what it is tied to.
Use it for a snapshot no Gmsh session can partition: a composed
model (Assembly(...).fem()) whose modules would otherwise be
one rank each, or a FEMData.from_h5 read. It replaces any
partition the snapshot carries; partition ids run 1 ..
n_parts like the mesh partitioner's, and n_parts=1 returns
an unpartitioned copy. self is unchanged.
Raises ValueError for n_parts < 1, fewer elements than
ranks, a negative or non-finite weight (zero is allowed: the
element is placed by position and costs nothing), all weights
zero, or a weights mapping that misses an element type.
Source code in src/apeGmsh/mesh/FEMData.py
with_constraint ¶
Return a new :class:FEMData with record appended.
Pure transform. self is unchanged. Dispatch is by record
type:
===================================== =================================
Record subclass Appended to
===================================== =================================
NodePairRecord nodes.constraints
NodeGroupRecord nodes.constraints
NodeToSurfaceRecord nodes.constraints
InterpolationRecord elements.constraints
SurfaceCouplingRecord elements.constraints
SPRecord nodes.sp
===================================== =================================
Routing an unknown record subclass raises TypeError — this
is a fail-loud contract because the compose engine needs every
record to land in a known broker bucket.
Source code in src/apeGmsh/mesh/FEMData.py
with_load ¶
Return a new :class:FEMData with record appended.
Pure transform. self is unchanged. Dispatch is by record
type:
===================================== =================================
Record subclass Appended to
===================================== =================================
NodalLoadRecord nodes.loads
ElementLoadRecord elements.loads
SPRecord nodes.sp
===================================== =================================
Source code in src/apeGmsh/mesh/FEMData.py
compose_tree ¶
Derived nested-compose tree view of self.composed_from.
Reconstructs the nested-compose hierarchy from this FEMData's
flat composed_from chain (per PR #369's flat-graft
storage). Returns a tuple of root
:class:~apeGmsh.mesh._compose.ComposeTreeNode instances;
each root carries its :class:ComposeRecord plus any direct
children parsed from joined labels via the separator-
alternation rule (depth-1 ., depth-2 /, depth-3
., ...).
Empty tuple when self.composed_from is empty (an
uncomposed FEMData).
Source code in src/apeGmsh/mesh/FEMData.py
with_mass ¶
Return a new :class:FEMData with record appended to
nodes.masses.
Pure transform. self is unchanged. Only
:class:~apeGmsh._kernel.records._masses.MassRecord is
accepted; anything else raises TypeError.
Source code in src/apeGmsh/mesh/FEMData.py
assess ¶
Compile a v1 :class:~apeGmsh.assess.AssessmentReport (ADR 0094).
figures=True writes one undeformed mesh still via
:meth:render. Default is False.
Source code in src/apeGmsh/mesh/FEMData.py
render ¶
render(path: 'str | Path', *, camera: 'str | None' = None, window_size: tuple[int, int] = (1280, 720)) -> 'Path | None'
Write one undeformed mesh still (ADR 0094 S1).
VTK offscreen — no Qt window, no event loop. Returns the
written :class:~pathlib.Path, or None (and prints the
[skip viewer] notice) under APEGMSH_SKIP_VIEWER=1 or
with no GL.
camera= defaults to xy for a planar model, iso
otherwise (ADR 0094 Amendment 3); pass it explicitly to
override.
Source code in src/apeGmsh/mesh/FEMData.py
viewer ¶
Open a non-interactive mesh viewer from this snapshot.
Currently disabled — the legacy Results.from_fem(...).viewer()
path was removed when the Results module was rebuilt. For a
headless mesh still use :meth:render. For an interactive
mesh window, use g.mesh.viewer().