Boolean geometry operations

Last changes: Documentation changelog

Problem statement

Boolean operations preserve operand structure in IR and do not perform hidden meshing at construction.

This page documents the public Python authoring boundary, not an undocumented runtime promise. Construction creates typed authoring data, while to_ir() is the object-level lowering boundary consumed by the study/script pipeline.

Governing equations

(1)\[q_{\mathrm{IR}} = \mathrm{geometry_boolean}(\text{qualified inputs})\]

The physical term or constraint is represented by the canonical IR object geometry_boolean. The exact discrete operator, quadrature, mesh treatment, and solver selection are backend responsibilities; this page does not replace their qualification evidence.

Symbols and SI units

Symbol

Meaning

SI unit

\(q\)

canonical typed authoring quantity

\(\mathrm{1}\)

All dimensional inputs are documented in SI units. Vector quantities use Cartesian components in the repository coordinate convention. Dimensionless parameters are explicitly marked 1; a default of None means that the constructor selects or omits the field according to the contract.

Assumptions and validity

Inputs are finite and typed. Positive lengths, densities, conductivities, temperatures, and material constants are rejected when the source constructor requires positivity. Unsupported combinations fail closed in the constructor or lowering boundary rather than being silently converted.

Python API

Constructor or function

fm.Difference(base, tool, name=”difference”), fm.Union(a, b), fm.Intersection(a, b)

Parameters

Python name

Type

Default

SI unit

Validation

Meaning

FEM/FDM CPU/GPU support

ProblemIR destination

base/tool or a/b

Geometry

required

1

typed geometry operands

boolean operands

FEM CPU/GPU: IR; FDM CPU/GPU: resolver-specific

operands

name

str

operation default

1

non-empty

result name

FEM/FDM CPU/GPU: IR; resolver-specific

name

Stage-first example

# %%
import fullmag as fm

study = fm.study("public-api-example")
study.objects.mesh.defaults(maximum_element_size=5e-9)
body = study.geometry(fm.Box(size=(100e-9, 20e-9, 5e-9)), name="film")
body.Ms = 800.0e3
body.Aex = 13.0e-12
body.alpha = 0.02
body.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.stages.add_relax(stage_id="api-example", dt=5e-13, max_steps=1)
# Author the documented object after the stage exists.
value = fm.Difference(fm.Box(size=(100e-9, 20e-9, 5e-9)), fm.Cylinder(radius=5e-9, height=5e-9))
canonical_ir = value.to_ir()

The example intentionally exposes the object-level boundary. In a full stage, attach canonical_ir through the corresponding study/module registration method; no implicit runtime route is inferred from this page.

ProblemIR

value.to_ir() is the canonical serialization boundary. It emits a typed geometry_boolean record with the fields listed above; nested geometry, targets, profiles, or material references remain nested typed records rather than opaque Python objects. The IR is the requested intent. Backend resolution must preserve the record or reject an unsupported combination.

Round-trip and failure semantics

The requested intent is preserved before resolved execution. Validation errors identify invalid inputs, while unsupported combinations are rejected.

A supported record is expected to round-trip through the repository script/scene representation without changing qualified values, units, or identifiers. Invalid types, missing required fields, non-finite values, contradictory options, and unsupported backend combinations are rejected with an explicit validation error. This page makes no claim that every backend accepts every legal authoring object.

Discrete realization

The FEM/FDM realization selects its own mesh, stencil or element operator, boundary treatment, and CPU/GPU execution lane. The Python contract supplies the physical inputs and canonical IR only; numerical equivalence requires the backend-specific validation named below.

Implementation mapping

The authoritative implementation is packages/fullmag-py/src/fullmag/model/geometry.py symbol class Difference. The public constructor signature, validation branches, defaults, and to_ir() field names are derived from that source, not from a historical example.

Validation

Focused repository tests covering this contract include: test_boolean_geometry_exports_nested_ir. These tests are evidence for authoring/IR behavior; live runtime, device performance, and Control Room browser behavior require separate qualification.

Limitations and Control Room

Python-authored Boolean CSG compositions (Union, Intersection, Difference) are surfaced read-only inside GeometryObjectPanel (Model Explorer -> Objects -> <object> -> Geometry) for inspection and placement. Interactive CSG creation buttons on the Ribbon remain gated behind preview: true and are excluded from the active toolbar, so authoring multi-body Boolean operations stays Python-only (not implemented in Control Room).

Control Room crosswalk

Python/API surface

Control Room path

Status

Transaction

Script-authored CSG geometry inspection & translation

Model Explorer -> Objects -> <object> -> Geometry (GeometryObjectPanel)

inspection-only (translation editable in ObjectPlacementPanel)

Scene load / fm.connect() sync

Multi-body Boolean CSG creation/editing (Union, Difference, Intersection)

Ribbon CSG controls (preview: true)

not implemented

Author in Python

Control Room Geometry Inspector displaying the Primitive Geometry box editor and Geometry/Placement tabs while Ribbon CSG creation remains hidden

See Control Room capability register and Geometry, Materials, Regions & Magnetic Textures.

Scientific bibliography

  • C. Geuzaine and J.-F. Remacle, Gmsh: a three-dimensional finite element mesh generator, Int. J. Numer. Meth. Eng. 79 (2009), DOI: https://doi.org/10.1002/nme.2579

Source code index

Source path

Symbol

Responsibility

packages/fullmag-py/src/fullmag/model/geometry.py

class Difference

public constructor and IR lowering

  • Implementation: packages/fullmag-py/src/fullmag/model/geometry.py::class Difference

  • Source-map: geometry/boolean-operations.source-map.json

  • Contract status: current constructor and to_ir() boundary documented against revision ab3c8802a691a535063102c12f9a79bb0043b367.