Code Documentation¶

Create an array of beams from a list of coordinates

COG and mass from a single curve-offset solve.

Equivalent to (get_cog(), get_mass()) but resolves the beam's curve offsets / absolute placement once instead of twice — Part.calculate_cog needs both per beam.

Returns node on beam from point

Returns node as a fraction of the beam length from n1-node.

Returns outer points of beam

Copy beam to new position

Bounding Box of beam

Create a plate representation of the beam.

This beam's (start, end) in global coordinates.

The nodes are expressed in the beam's own frame, so a beam inside a placed :class:~ada.Part has to be pushed through the accumulated placement. Exporters share this so they cannot disagree on where a beam is — the Genie SAT body imprints the axis onto the plates and the XML references the resulting edge, and the two must land on each other.

Sweep the section profile along the axis curve (a fixed-reference sweep).

The profile is placed at the first node, its plane perpendicular to the chord (a stable, twist-free reference); the directrix is the exact 3D curve, so the swept solid follows the real arc, not the chord.

All 6 dofs are fixed

All 3 translational dofs are fixed, and all 3 rotational dofs are free.

Revolve the section profile around the curve's rotation axis.

The profile is placed perpendicular to the arc at p1 and revolved. The placement frame is X = radial (p1 -> away from axis), Y = rotation axis (the section "up"), Z = arc tangent (the profile normal).

The revolution axis is in global coordinates — the convention both CAD backends build from. The IFC writer converts it to the Position-local frame that IfcRevolvedAreaSolid.Axis requires.

Fast constructor for flat FEM shell elements (3- or 4-gon, no arcs/radii).

Geometrically equivalent to from_3d_points for a radius-free polygon, but it (a) computes the orientation once and injects it via :meth:Placement.from_dirs_precomputed, so the computed-placement LRU is never touched (it thrashes on per-element placements), and (b) builds the closed line loop directly instead of running build_polycurve / SegCreator. Used only by the FEM shell -> Plate conversion; the general from_3d_points path (arcs, fillets, radii) is unchanged.

Vectorized :meth:from_fem_shell for m same-arity k-gons (m, k, 3).

The per-element orientation/projection math runs once over arrays (:func:ada.core.vector_transforms.shell_orientations_bulk — same floating-point operation order and Decimal rounding as the scalar chain); only the output objects (Point/LineSegment/Node) are built per element. Rows the bulk math can't take (degenerate corners/edges) return None — the caller runs those through from_fem_shell.

Ordered, closed loop of 3D segments from ordered corner points + optional PlateEdgeCurve.

Consecutive corners form each edge; an edge whose endpoints match a spec becomes an ArcSegment (circle/ellipse) or SplineSegment, otherwise a LineSegment. Endpoint match is winding-agnostic; an unmatched spec (e.g. a corner pruned as collinear) just leaves that edge straight. Feed the result to :meth:from_segments / Plate.from_segments.

Construct directly from an ordered, closed loop of 3D segments (line/arc/spline).

Unlike :meth:from_3d_points this neither samples nor rebuilds the boundary via build_polycurve: each segment is carried through to both the 3D and the projected 2D outline as-is (arc midpoints, spline curves preserved), so analytic edges survive to IFC/STEP and are discretized only downstream at tessellation. Orientation is derived from the corner points exactly like :meth:from_3d_points (Placement.from_co_linear_points), so a segments-built plate sits in the same frame a points-built one would.

Build a plate whose outline is an ordered list of LineSegment/ArcSegment/SplineSegment.

Use this instead of from_3d_points when the boundary is genuinely a mix of line and analytic curve edges (e.g. an ACIS/SAT plate with a circular or spline boundary): the segments are carried verbatim rather than sampled into a point cloud and rebuilt, so arcs/splines survive analytically into IFC/STEP and are discretized only downstream at tessellation.

Fast Plate constructor for flat FEM shell elements (no arcs/radii).

Equivalent geometry to from_3d_points but routed through CurvePoly2d.from_fem_shell, which skips build_polycurve and the computed-placement LRU. See :meth:CurvePoly2d.from_fem_shell.

detached yields a transient plate (no material back-reference) for streaming exporters that build, emit and discard it — see :meth:ada.Part.iter_objects_from_fem.

Bounding Box of plate

Plate centroid in global coordinates.

Convention: - poly.points2d are expressed in the plate's 2D local system (X,Y). - poly.origin is the local 3D origin of that 2D system. - poly.xdir defines local X direction in 3D. - poly.normal defines local Z (plane normal) in 3D. - local Y is constructed as (normal × xdir) to enforce right-hand rule.

The centroid is found in the local system of the plate, and moved to global coordinates by the absolute placement of the plate.

This plate's outline and normal in global coordinates.

poly.points3d is expressed in the plate's own frame, so a plate that sits inside a placed :class:~ada.Part has to be pushed through the accumulated placement before being written out. Exporters share this so they cannot disagree on where a plate is (the Genie SAT body used to ignore part placements entirely while the polygon writer honoured them).

Construct a PlateCurved from a raw OCC TopoDS_Face.

Bypasses the :class:~ada.geom.Geometry → :class:~ada.geom.surfaces.AdvancedFace round-trip that the regular __init__ path relies on. The loft tool uses this when it already has the OCC face from BRepOffsetAPI_ThruSections — going via AdvancedFace would only re-decode the same surface back into OCC, and the occ_face_to_ada_face → make_face_from_geom round-trip currently has a bounds-structure mismatch (the STEP reader emits raw curve types as AdvancedFace.bounds while the OCC builder expects FaceBound wrappers around EdgeLoops).

Behaviour: solid_occ returns the wrapped face directly; extruded_solid_occ extrudes it along its normal; nodes walks the face's outer wire. The geom / solid_geom accessors return None — callers that need an adapy Geometry must use the __init__ constructor instead.

The gxml curved_shell sense flag (does the desired shell normal agree with the wrapped face's own normal). Authored data preserved by the gxml reader in metadata["props"]["gxml_sense_flag"]; defaults to True.

Sense-corrected unit thickness direction: the wrapped face's own oriented normal (probed kernel-free at a representative parameter), flipped when the gxml sense flag is false. None when the surface has no kernel-free probe.

The plate's SOLID geometry: a thickness-t analytic ClosedShell (built kernel-free by :func:ada.geom.primitive_brep.face_to_thick_shell, honouring Config().geom_thickness_anchor) when Config().geom_thicken_curved_shells is on and the face is thickenable — else the bare face Geometry as before.

Prism-extrude the curved face by t along its normal so the rendered plate carries thickness like a planar Plate.from_3d_points does.

Returns a backend ShapeHandle (Solid) ready for the tessellator. Falls back to the bare face shape on any prism failure so the caller still gets something to render.

Construct a thickness-less curved surface from a raw OCC face.

Mirrors :meth:PlateCurved.from_occ_face but pins thickness to zero so downstream rendering emits the bare face.

Copy the box to a new position and/or rotation.

Drop transient OCC state when pickling.

_occ_cache may hold a TopoDS_Shape (STEP/SAT import, or the cached transform result above) — OCC objects aren't picklable, and even when wrapped in some forks they don't survive a process boundary cleanly. Callers that need the OCC body after unpickling can rebuild it via :meth:solid_occ from the parametric _geom; raw-OCC Shapes lose their geometry on round-trip, which is the honest answer (we don't have a serialisable representation for arbitrary OCC bodies).

Import from IFC file.

reader="native" uses adacpp's pure-C++ IFC reader (IfcNgeomStream) to build a geometry-shapes Part/ShapeProxy tree (no ifcopenshell/OCC) — colour + spatial hierarchy from the C++ resolver; does NOT reconstruct typed Beam/Plate objects. Default (ifcopenshell) is the full typed reader.

Import a Finite Element model. Currently supported FEM formats: Abaqus, Sesam and Calculix

Parameters:

Create a FEM input file deck for executing fem analysis in a specified FEM format. Currently there is limited write support for the following FEM formats:

Open Source

• Calculix
• Code_Aster

not open source

• Abaqus
• Usfos
• Sesam

Write support is added on a need-only-basis. Any contributions are welcomed!

Parameters:

Note! Meshio implementation currently only supports reading & writing elements and nodes.

'ecc_to_mpc': Runs the method :func:`~ada.fem.FEM.convert_ecc_to_mpc` . Default is True
'hinges_to_coupling': Runs the method :func:`~ada.fem.FEM.convert_hinges_2_couplings` . Default is True

Important Note! The ecc_to_mpc and hinges_to_coupling will make permanent modifications to the model.
If this proves to create issues regarding performance this should be evaluated further.

Serialize this Assembly to a pickle file (round-trips via :func:ada.from_pickle).

adapy objects are kept picklable on purpose — backend CAD bodies live in the transient _occ_cache slot, not on the object — so the parametric model round-trips cleanly. Lets a source parsed once be reused for many exports without re-reading/re-parsing it.

Write a Genie (DNV) concept XML.

embed_sat embeds the plate geometry as a ready-built ACIS SAT body that each <flat_plate> references by face name. Without it the plates are written as bare polygons and Genie must rebuild — and imprint — the ACIS itself on import, which dominates load time on a large model. It needs a CAD backend (see CadBackend.imprint_planar_faces).

Defaults to None = on whenever it can be produced. It can't be with merge_strategy, which sources plates from the FEM-shell face engine without ever materialising the Plate objects the SAT body is built from; asking for both explicitly is contradictory and raises rather than quietly dropping one.

streaming emits the per-object <structure> entries straight to the file instead of building the whole DOM, cutting peak RSS on large FEM-derived models. It composes with embed_sat (the SAT body itself is inherently whole-model, so only the concept entries stream).

merge_strategy (None | "none" | "coplanar" | ...) sources plates from the object-free vectorized FEM-shell face engine — streaming path only.

Write a Genie (DNV) workspace file (.gnx).

The workspace is the concept XML to_genie_xml writes plus its ACIS body, zipped the way Genie saves one — so the OS association opens the model straight into Genie, with no import step. The SAT body is always built (this is embed_sat=True; a workspace has no polygon-only mode because Genie stores the body beside the XML, never rebuilds it).

streaming/merge_strategy take the streaming XML writer's route through a temporary XML and repack it, for large FEM-derived models.

This method takes a Joint element containing two intersecting beams. It will check with the existing list of joints to see whether or not it is part of a larger more complex joint. It usese primarily two criteria.

Criteria 1: If both elements are in an existing joint already, it will u

Criteria 2: If the intersecting point coincides within a specified tolerance (currently 10mm) with an exisiting joint intersecting point. If so it will add the elements to this joint. If not it will create a new joint based on these two members.

Return every Weld at or below this Part whose members include member.

Add each unique section exactly once. Returns a map original_section -> container_section.

Add each unique material exactly once. Returns a map original_material -> container_material.

Batch-add beams and plates. Returns the list of added (or existing) objects. Only supports Beam/BeamTapered and Plate for now.

Parameters:

Build Beams and Plates from the contents of the local FEM object.

merge folds the one-object-per-element output back down by merging coplanar shell plates (same material + thickness) and colinear beams (same section + material). Best-effort: a group is merged only when it collapses cleanly, else its elements are kept. Defaults off here to keep the 1:1 element→object mapping callers expect; the FEM→CAD conversion path opts in (merge_fem_objects).

reconstruct_surfaces (opt-in) instead recovers smooth structured quad panels as single curved plates (NURBS B-rep) — a large size/time reduction for CAD export of meshes generated from curved panels. Non-reconstructable elements fall back to flat plates (coplanar-merged when merge is on). Beams are unaffected.

Lazily build concept objects from this part's FEM mesh.

Streaming sibling of :meth:create_objects_from_fem: yields one object at a time WITHOUT materialising the full set or adding them to the part's containers, so a streaming exporter (e.g. Assembly.to_ifc(streaming=True)) keeps peak memory bounded. Beams are yielded before plates.

detached (default) yields transient plates carrying no material back-reference, so each frees as soon as the consumer drops it.

merge_strategy selects how shells fold into plates: None (default) keeps the legacy 1:1 element→plate mapping; any strategy value ("coplanar"/...) sources plates from the object-free vectorized face engine (:func:ada.fem.formats.mesh_faces.faces_from_fem) and wraps each merged face in a single transient :class:Plate. This is the one place the merge strategy lives, so every streaming consumer (Genie XML, IFC, STEP) folds shells the same way. Beams are unaffected (they fold via the colinear pass on the object create path; the strategy is shell-only).

mat_cache (name → :class:Material) lets the caller pin which material objects the plates reference — pass the already-consolidated materials so the streamed plates share the exporter's material identity (else a post-consolidation materials.add would mint a fresh copy).

Get part by name.

Get element of any type by its name.

Moves all sections from all sub-parts to this part

Single source of truth for iterating welds across the part tree.

Welds live in Part._welds — a container intentionally separate from get_all_physical_objects because the IFC / FEM / GXML writers can't process them (no .material, no solid_geom until the Weld.solid_geom delegation, etc.). The GLB pipeline composes both iterators explicitly: tessellation + GraphStore add welds via this method on top of the physical objects. Avoids scattering include_welds=False opt-outs across every non-GLB caller.

For all beams in a Assembly get all beams touching or within the beam. Essentially a clash check is performed and it returns a dictionary of all beam ids and the touching beams. A margin to the beam volume can be included.

Parameters:

Returns:

Copy the part and all its sub_parts to a new part. Optionally add translation and/or rotation to the new part

Create a Trimesh.Scene from ada.Part.

Render the part to a PIL Image.

Parameters¶

camera Legacy pygfx camera. When supplied with backend="pygfx", the trimesh-scene render path is used (kept for callers that already pass a hand-built Camera). When None, both backends route through the embed's applyCameraPreset math so pygfx, chromium, and the live 3D viewer all use identical camera setup. backend "pygfx" (default) — fast offscreen render via wgpu. "chromium" drives the production adapy embed in headless Chromium via Playwright. camera is ignored by chromium; pass preset to override the embed's CameraPreset. preset Camera preset dict (azimuth_deg, elevation_deg, fov_deg, distance, margin, …). Honored by both backends when camera is None — same field names as paradoc.camera.presets.CameraPreset so the three render paths read from a single source of truth. size Viewport size (also the output PNG size at DPR=1).

Attach a port to this equipment (sets port.parent).

This equipment's own ports, followed by those of any nested child Equipment. A vessel modelled with sub-compartments hangs each compartment's nozzles on a child equipment one level down, so the nozzle list of the item as a whole is only complete with those included. include_nested=False returns :attr:ports unchanged.

Connect the named port to system (delegates to system.connect).

World position of the port. Note: adds the parent's origin only — equipment rotation is not modeled (Equipment carries no Placement frame).

Connect this system to a port, in either of two shapes: connect(equipment, port_name) looks the port up by name (the original, string-lookup form); connect(port) -- one argument, no port_name -- takes the :class:Port object directly, e.g. whatever equipment.add_port(...) returned. The direct form is sturdier (a typo'd name fails where the port was built, not three lines later here) and is what :meth:add_leg accepts too; the name-lookup form stays for the common case of wiring against equipment you didn't just construct yourself. Returns self so connections chain fluently.

Connect this system directly to an already-built :class:Port -- the piece :meth:connect and :meth:add_leg share. Same validation as the name-lookup form of :meth:connect: the port's category must match this system's, and it must not already belong to another system.

Connect one branch leg -- a from/to port pair -- as a named :class:~.segments.SystemSegment. Two or more legs sharing a junction equipment (three or more runs meeting at a fitting) turn this system into a branch: ada.topology.routing.route_system detects that shape and routes every leg instead of just ports[0]/ports[-1].

start/end each take either shape :meth:connect does -- a :class:Port object, or an (equipment, port_name) pair -- and may mix (one as a Port, the other by name). Returns self so legs chain fluently, e.g.::

system = (
    PipingSystem("L-301")
    .add_leg("L-301/1", vessel_out, tee_n1)
    .add_leg("L-301/2", tee_n2, pump_a_in)
    .add_leg("L-301/3", tee_n3, pump_b_in)
)

Terminate this system at a fixed site location — a site input or site output — rather than an equipment port. This is where the system crosses the model boundary (grid supply, cooling-water make-up, a drain to site, …). position is a world-space point; direction must be IN (into the site) or OUT (out of the site). Returns self so it chains fluently with :meth:connect.

Route this system through grid and generate its geometry. Convenience wrapper over ada.topology.routing — returns self.route_geometry.

Every port on every piece of equipment, in equipment order.

Read a DEXPI P&ID -- either flavour, sniffed from the root tag -- into a system model.

This reads and resolves; it does not build. Every item resolves through the equipment definition list to a physical envelope with real ports, and every PipingNetworkSegment and signal line becomes a system joining them. No coordinates: a P&ID says what exists and what is connected to what, and nothing about where any of it stands.

definitions is the equipment definition list (a path to JSON/XLSX, a loaded dict, or None for the shipped class defaults). inline_components="equipment" materialises each in-line valve as its own small equipment rather than recording it in the run's metadata -- it decides what exists, which is why it is a read argument and deck bounds are not.

Nothing is dropped quietly. Everything the read could not carry -- a segment whose ends the P&ID never named, an item that resolved to nothing placeable -- lands in :attr:report and is summarised in one warning; strict=True raises instead. Gaps found while building are a different failure with a different fix, and are reported separately on the assembly the build produces.

Build a 3D model: generate decks, place the equipment on them, route the systems.

spec (a :class:~ada.topo_model.build_spec.ProceduralBuildSpec) carries every choice the build makes -- deck bounds, design ruleset, structural blueprint, whether to route, whether to feed routing failures back into the layout. Defaults build a routed model with the standard rules.

The result is a new assembly and this model is unchanged, so a second build with different rules starts from the same resolved input rather than from the first build's output.

Write this model out as a DEXPI P&ID.

The default is a merge, not a regeneration: it starts from :attr:source_document and re-serializes the equipment, ports and systems adapy owns from the live objects, so an edit made in Python lands in the output, while everything the source carried that adapy does not model -- the shape catalogue, presentation, attributes this branch does not touch -- is echoed back verbatim.

from_scratch=True writes a brand-new document from the live objects alone. It is the only option for a model with no source document, and lossy by construction even for one that has it: there is no chamber, no piping class and no schematic drawing on the live objects to write back.

A placement from a rotation matrix whose columns are the world directions of the local axes

Axis is a list of 3 floats, angle is in degrees.

Create a placement from a list of points that are co-linear.

Build a Placement whose ComputedPlacement is injected directly.

The lazy xdir/ydir/zdir getters short-circuit on a populated _computed_placement (see :meth:xdir), so accessing the directions never calls the global get_computed_placement_cached LRU. That cache thrashes on FEM meshes (a distinct placement per element), so the fast shell path computes the orientation once and injects it here.

The three directions must already be normalized and rounded to match the output of compute_orientation_vec (i.e. what the LRU path would have produced), otherwise geometry will not match the general construction.

This placement accumulated through its owner's ancestry.

Treat the result as read-only. It was already free to be self (an unparented placement is its own absolute placement), and the fast paths below widen that: elements sharing a container can be handed the same resolved object.

Rotate the placement around an axis. Returns a new placement.

Transforms a point p from the local system into absolute/global, using self.placement. If identity, returns p unchanged.

Transform a vector using optimized caching.

Local (2d or 3d) points to the parent system. The same as :meth:transform_local_points_to_global.

Transform points from the global coordinate system to the coordinate system of this placement.

Transform points from the global coordinate system to the coordinate system of this placement.

Returns a new Placement with the zdir transformed to match new_zdir.

Make a copy of this placement

Parameters:

Add an analysis step to the assembly

Adds a reference point in assembly with a specific name

Nodes used for interfacing between other parts. Pass a custom Constraint if specific coupling is needed

Converts structural object to FEM elements. Currently only BEAM is supported

Get all the boundary conditions in the entire assembly

Get all the Masses in the entire assembly

All 6 dofs are fixed

All 3 translational dofs are fixed, and all 3 rotational dofs are free.

Assuming uniqueness of Material Name and parent

TODO: Make this check for same Material Model parameters

Parameters:

Returns:

Make a copy of the material with a new name and parent

Create a section from a string representation. If tapered, returns a list of two sections

Make a copy of the section