yapcad.package.analysis package

Submodules

yapcad.package.analysis.base module

Shared data structures for analysis/validation plans.

class yapcad.package.analysis.base.AnalysisAdapter

Bases: ABC

Base class for solver adapters.

name: str = 'analysis-adapter'

abstractmethod run(manifest, plan: AnalysisPlan, workspace: Path, **kwargs: Any) → AnalysisResult

Execute the plan and return an AnalysisResult.

class yapcad.package.analysis.base.AnalysisPlan(plan_id: str, kind: str, backend: str, name: str | None = None, description: str | None = None, geometry: Dict[str, ~typing.Any]=<factory>, materials: Dict[str, ~typing.Any]=<factory>, loads: Dict[str, ~typing.Any]]=<factory>, boundary_conditions: Dict[str, ~typing.Any]]=<factory>, acceptance: Dict[str, ~typing.Any]=<factory>, backend_options: Dict[str, ~typing.Any]=<factory>, execution: ExecutionConfig = <factory>, attachments: Dict[str, ~typing.Any]]=<factory>, metadata: Dict[str, ~typing.Any]=<factory>, raw: Dict[str, ~typing.Any]=<factory>)

Bases: object

Representation of a validation/analysis plan loaded from YAML.

acceptance: Dict[str, Any]

attachments: List[Dict[str, Any]]

backend: str

backend_options: Dict[str, Any]

boundary_conditions: List[Dict[str, Any]]

description: str | None = None

execution: ExecutionConfig

geometry: Dict[str, Any]

kind: str

loads: List[Dict[str, Any]]

materials: Dict[str, Any]

metadata: Dict[str, Any]

name: str | None = None

property normalized_backend: str

plan_id: str

raw: Dict[str, Any]

class yapcad.package.analysis.base.AnalysisResult(plan_id: str, status: str, metrics: Dict[str, ~typing.Any]=<factory>, summary: Dict[str, ~typing.Any]=<factory>, artifacts: Dict[str, ~typing.Any]]=<factory>, summary_path: Path | None = None, backend: str | None = None, timestamp: str | None = None, notes: str | None = None)

Bases: object

Container for results emitted by analysis adapters.

artifacts: List[Dict[str, Any]]

backend: str | None = None

metrics: Dict[str, Any]

notes: str | None = None

plan_id: str

status: str

summary: Dict[str, Any]

summary_path: Path | None = None

timestamp: str | None = None

to_manifest_entry(package_root: Path) → Dict[str, Any]

class yapcad.package.analysis.base.ExecutionConfig(mode: str = 'local', command: str | None = None, transport: str | None = None, host: str | None = None, workdir: str | None = None, env: Dict[str, str]=<factory>, options: Dict[str, ~typing.Any]=<factory>, license: Dict[str, ~typing.Any]=<factory>)

Bases: object

Execution context for an analysis plan.

command: str | None = None

env: Dict[str, str]

host: str | None = None

property is_remote: bool

license: Dict[str, Any]

mode: str = 'local'

options: Dict[str, Any]

transport: str | None = None

workdir: str | None = None

yapcad.package.analysis.base.available_backends() → Sequence[str]

yapcad.package.analysis.base.get_backend(name: str) → Type[AnalysisAdapter] | None

yapcad.package.analysis.base.load_plan(path: Path | str) → AnalysisPlan

Load a YAML analysis plan and return the normalised AnalysisPlan.

yapcad.package.analysis.base.register_backend(name: str, adapter_cls: Type[AnalysisAdapter]) → None

yapcad.package.analysis.calculix module

CalculiX backend for yapCAD analysis plans.

class yapcad.package.analysis.calculix.CalculixAdapter

Bases: AnalysisAdapter

Create a simplified axisymmetric disk model and execute CalculiX when available.

name: str = 'calculix'

run(manifest: PackageManifest, plan: AnalysisPlan, workspace: Path, **_: Any) → AnalysisResult

Execute the plan and return an AnalysisResult.

yapcad.package.analysis.cli module

Command-line helpers for running analysis plans.

yapcad.package.analysis.cli.analyze_package(package_path: Path | str, plan_path: Path | str, *, status: str = 'pending') → Path

Record analysis metadata for plan_path inside package_path.

This helper prepares the results directory, writes a summary.json placeholder, and updates the manifest validation.results block.

yapcad.package.analysis.cli.main(argv: Sequence[str] | None = None) → int

yapcad.package.analysis.face_naming module

Face naming system for boundary condition assignment.

This module provides utilities for naming faces of yapCAD solids, which can then be used to assign boundary conditions in analysis plans.

Face names can be assigned: 1. At creation time via DSL with { face_names: {…} } syntax 2. Post-hoc via selectors (by normal, by area, by position) 3. Interactively in the viewer (future)

The face names are stored in solid metadata and propagate through to Gmsh physical groups when meshing.

Copyright (c) 2025 yapCAD contributors MIT License

class yapcad.package.analysis.face_naming.ByAreaSelector(min_area: float | None = None, max_area: float | None = None, largest: bool = False, smallest: bool = False)

Bases: FaceSelector

Select faces by area criteria.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

set_context(faces: List[FaceInfo]) → None

Set all faces for largest/smallest comparison.

class yapcad.package.analysis.face_naming.ByNormalSelector(direction: Tuple[float, float, float], tolerance_deg: float = 5.0, allow_reversed: bool = False)

Bases: FaceSelector

Select faces by normal direction.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

class yapcad.package.analysis.face_naming.ByPositionSelector(axis: str = 'z', at_min: bool = False, at_max: bool = False, above: float | None = None, below: float | None = None, tolerance: float = 1e-06)

Bases: FaceSelector

Select faces by centroid position.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

set_context(faces: List[FaceInfo]) → None

Set all faces for min/max comparison.

class yapcad.package.analysis.face_naming.CombinedSelector(selectors: List[FaceSelector], mode: str = 'and')

Bases: FaceSelector

Combine multiple selectors with AND/OR logic.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

set_context(faces: List[FaceInfo]) → None

Propagate context to child selectors.

class yapcad.package.analysis.face_naming.FaceInfo(index: int, centroid: ~typing.Tuple[float, float, float], normal: ~typing.Tuple[float, float, float], area: float, name: str | None = None, tags: ~typing.List[str] = <factory>)

Bases: object

Information about a face for selection/naming.

index

Face index in the solid

Type:

int

centroid

Face centroid point

Type:

Tuple[float, float, float]

normal

Face normal vector (average for curved faces)

Type:

Tuple[float, float, float]

area

Face area

Type:

float

name

Optional assigned name

Type:

str | None

tags

Optional list of tags

Type:

List[str]

area: float

centroid: Tuple[float, float, float]

index: int

name: str | None = None

normal: Tuple[float, float, float]

tags: List[str]

class yapcad.package.analysis.face_naming.FaceNamer(solid: Any)

Bases: object

Utility for naming faces of yapCAD solids.

This class extracts face information from solids and applies names based on selectors or explicit assignments.

property faces: List[FaceInfo]

Get list of face information.

get_named_faces() → Dict[str, List[int]]

Get all named faces.

Returns:

Mapping of names to face indices

name_faces(assignments: Dict[str, FaceSelector | List[int]]) → Dict[str, List[int]]

Apply face name assignments.

Parameters:

assignments – Mapping of names to selectors or explicit face indices

Returns:

Mapping of names to matched face indices

to_metadata() → Dict[str, Any]

Convert face naming to metadata format.

Returns:

Dictionary suitable for solid metadata

class yapcad.package.analysis.face_naming.FaceSelector

Bases: object

Base class for face selection predicates.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

yapcad.package.analysis.face_naming.back_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with -Y normal (back faces).

yapcad.package.analysis.face_naming.bottom_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with -Z normal (bottom faces).

yapcad.package.analysis.face_naming.faces_at_z_max(tolerance: float = 1e-06) → ByPositionSelector

Select faces at maximum Z coordinate.

yapcad.package.analysis.face_naming.faces_at_z_min(tolerance: float = 1e-06) → ByPositionSelector

Select faces at minimum Z coordinate.

yapcad.package.analysis.face_naming.front_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with +Y normal (front faces).

yapcad.package.analysis.face_naming.largest_face() → ByAreaSelector

Select the largest face by area.

yapcad.package.analysis.face_naming.left_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with -X normal (left faces).

yapcad.package.analysis.face_naming.right_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with +X normal (right faces).

yapcad.package.analysis.face_naming.smallest_face() → ByAreaSelector

Select the smallest face by area.

yapcad.package.analysis.face_naming.top_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with +Z normal (top faces).

yapcad.package.analysis.fenics module

FEniCSx (DOLFINx) backend for yapCAD structural analysis.

This module provides FEA capabilities using FEniCSx/DOLFINx with Gmsh meshing. The key advantage is OCC kernel alignment: yapCAD, Gmsh, and FEniCSx all use OpenCASCADE, enabling direct geometry passing without lossy conversions.

Supported analysis types: - Linear elastic static analysis - Thermal analysis (future) - Modal analysis (future)

Usage:

from yapcad.package.analysis.fenics import FenicsxAdapter

adapter = FenicsxAdapter() result = adapter.run(manifest, plan, workspace)

Installation:

conda create -n yapcad-fenics -c conda-forge fenics-dolfinx gmsh pythonocc-core

Copyright (c) 2025 yapCAD contributors MIT License

class yapcad.package.analysis.fenics.FenicsxAdapter

Bases: AnalysisAdapter

FEniCSx (DOLFINx) FEA backend for structural analysis.

This adapter performs linear elastic static analysis using FEniCSx with Gmsh for mesh generation. It supports:

• Fixed boundary conditions (displacement = 0)

• Pressure loads on faces

• Point loads (concentrated forces)

• Traction (distributed force) on faces

Results include: - Maximum displacement - Maximum von Mises stress - Displacement and stress fields (VTU export)

name: str = 'fenics'

run(manifest: Any, plan: AnalysisPlan, workspace: Path, **kwargs: Any) → AnalysisResult

Execute the FEA analysis.

Parameters:

• manifest – Package manifest

• plan – Analysis plan specification

• workspace – Working directory for intermediate files

Returns:

AnalysisResult with metrics and artifacts

class yapcad.package.analysis.fenics.MaterialProperties(youngs_modulus: float, poisson_ratio: float, density: float = 0.0)

Bases: object

Linear elastic material properties.

density: float = 0.0

property lame_lambda: float

First Lamé parameter.

property lame_mu: float

Second Lamé parameter (shear modulus).

poisson_ratio: float

youngs_modulus: float

yapcad.package.analysis.fenics.fenics_available() → bool

Return True if FEniCSx (DOLFINx) is available.

yapcad.package.analysis.fenics.require_fenics() → None

Raise error if FEniCSx is not available.

yapcad.package.analysis.gmsh_mesher module

Gmsh meshing integration for yapCAD analysis.

This module provides meshing capabilities using Gmsh’s OCC integration, enabling direct geometry transfer from yapCAD’s OCC-based BREP representation.

The key advantage is that both yapCAD and Gmsh use the OpenCASCADE kernel, so geometry can be passed directly without lossy STEP/IGES conversions.

Usage:

from yapcad.package.analysis.gmsh_mesher import GmshMesher, MeshHints

mesher = GmshMesher() mesh = mesher.mesh_from_solid(solid, hints=MeshHints(element_size=2.0)) mesher.export_mesh(workspace / “model.msh”)

Copyright (c) 2025 yapCAD contributors MIT License

class yapcad.package.analysis.gmsh_mesher.GmshMesher(model_name: str = 'yapCAD_model')

Bases: object

Primary meshing interface using Gmsh’s OCC integration.

This class provides meshing capabilities for yapCAD solids using Gmsh. It leverages the shared OCC kernel between yapCAD and Gmsh for direct geometry transfer without intermediate file formats.

Example

mesher = GmshMesher() mesher.initialize() mesher.import_solid(solid) mesher.set_physical_groups({“fixed_face”: [1, 2], “load_face”: [3]}) mesher.generate_mesh(hints) mesher.export_mesh(Path(“output.msh”)) mesher.finalize()

export_mesh(path: Path, format: str | None = None) → Path

Export the mesh to a file.

Parameters:

• path – Output path

• format – Optional format override (msh, vtk, xdmf, su2)

Returns:

Path to the exported file

finalize() → None

Finalize Gmsh and release resources.

generate_mesh(hints: MeshHints | None = None, dim: int = 3) → None

Generate the mesh.

Parameters:

• hints – Mesh generation hints

• dim – Mesh dimension (2 for surface, 3 for volume)

get_mesh_stats() → Dict[str, Any]

Get mesh statistics.

Returns:

Dictionary with node count, element counts by type, quality metrics

import_solid(solid: Any, face_names: Dict[str, List[int]] | None = None, use_stl: bool = False) → List[Tuple[int, int]]

Import a yapCAD solid into Gmsh.

This uses Gmsh’s OCC integration to import the geometry directly from the OCC representation, avoiding STEP/IGES conversion losses.

Parameters:

• solid – yapCAD solid (must have OCC BREP representation)

• face_names – Optional mapping of face names to face indices

• use_stl – If True, use STL (tessellated) representation which may be more robust for complex geometries with topology issues

Returns:

List of (dim, tag) tuples for imported entities

import_step(step_path: Path) → List[Tuple[int, int]]

Import geometry from a STEP file.

Parameters:

step_path – Path to the STEP file

Returns:

List of (dim, tag) tuples for imported entities

initialize(verbose: bool = True, geometry_tolerance: float = 0.1) → None

Initialize Gmsh (must be called before other operations).

Parameters:

• verbose – If True, enable terminal output for progress monitoring

• geometry_tolerance – Tolerance for geometry repair operations

set_physical_groups(groups: Dict[str, List[int]], dim: int = 2) → None

Define physical groups for boundary conditions.

Physical groups associate mesh entities with names that can be used to apply boundary conditions in the solver.

Parameters:

• groups – Mapping of group names to entity tags

• dim – Dimension of entities (2 for faces, 3 for volumes)

set_physical_groups_by_normal(groups: Dict[str, Tuple[float, float, float]], tolerance_deg: float = 5.0) → None

Define physical groups by face normal direction.

This is useful for automatically identifying faces like “top”, “bottom”, “front”, etc. based on their orientation.

Parameters:

• groups – Mapping of group names to normal vectors (x, y, z)

• tolerance_deg – Angular tolerance in degrees

class yapcad.package.analysis.gmsh_mesher.MeshHints(element_size: float = 5.0, min_element_size: float | None = None, max_element_size: float | None = None, algorithm_2d: int = 6, algorithm_3d: int = 1, element_order: int = 1, optimize: bool = True, optimize_netgen: bool = False, refinement_fields: Dict[str, ~typing.Any]]=<factory>, geometry_tolerance: float = 0.0001, recover_3d: bool = True, use_stl: bool = False, scale_factor: float = 1.0)

Bases: object

Mesh generation hints for Gmsh.

element_size

Target element size (mesh density)

Type:

float

min_element_size

Minimum element size

Type:

float | None

max_element_size

Maximum element size

Type:

float | None

algorithm_2d

2D meshing algorithm (1=MeshAdapt, 2=Auto, 5=Delaunay, 6=Frontal-Delaunay)

Type:

int

algorithm_3d

3D meshing algorithm (1=Delaunay, 4=Frontal, 10=HXT)

Type:

int

element_order

Element polynomial order (1=linear, 2=quadratic)

Type:

int

optimize

Whether to optimize mesh quality

Type:

bool

optimize_netgen

Use Netgen optimizer for 3D meshes

Type:

bool

refinement_fields

List of refinement field specifications

Type:

List[Dict[str, Any]]

geometry_tolerance

Tolerance for geometry healing (default 1e-4)

Type:

float

recover_3d

If False, skip 3D mesh generation and do 2D only

Type:

bool

stl_fallback

If True, use STL intermediate format when BREP fails

algorithm_2d: int = 6

algorithm_3d: int = 1

element_order: int = 1

element_size: float = 5.0

geometry_tolerance: float = 0.0001

max_element_size: float | None = None

min_element_size: float | None = None

optimize: bool = True

optimize_netgen: bool = False

recover_3d: bool = True

refinement_fields: List[Dict[str, Any]]

scale_factor: float = 1.0

use_stl: bool = False

class yapcad.package.analysis.gmsh_mesher.PhysicalGroup(name: str, dim: int, tags: List[int])

Bases: object

A named group of mesh entities (for boundary conditions).

name

Human-readable name for the group

Type:

str

dim

Dimension (0=point, 1=edge, 2=face, 3=volume)

Type:

int

tags

Gmsh entity tags in this group

Type:

List[int]

dim: int

name: str

tags: List[int]

yapcad.package.analysis.gmsh_mesher.gmsh_available() → bool

Return True if Gmsh Python API is available.

yapcad.package.analysis.gmsh_mesher.mesh_solid(solid: Any, output_path: Path, hints: MeshHints | None = None, physical_groups: Dict[str, List[int]] | None = None, dim: int = 3) → Dict[str, Any]

Convenience function to mesh a solid and export.

Parameters:

• solid – yapCAD solid to mesh

• output_path – Path for output mesh file

• hints – Mesh generation hints

• physical_groups – Optional face groups for BCs

• dim – Mesh dimension

Returns:

Mesh statistics dictionary

yapcad.package.analysis.gmsh_mesher.require_gmsh() → None

Raise error if Gmsh is not available.

yapcad.package.analysis.schema module

Validation test schema implementation.

This module provides schema validation for yapCAD validation plans and results as specified in docs/validation_schema.rst.

Schema Version: validation-schema-v0.1

class yapcad.package.analysis.schema.ComparisonOp(*values)

Bases: Enum

Acceptance criteria comparison operators.

APPROX = '~='

EQ = '=='

GE = '>='

GT = '>'

LE = '<='

LT = '<'

class yapcad.package.analysis.schema.ResultStatus(*values)

Bases: Enum

Result status values.

ERROR = 'error'

FAILED = 'failed'

PASSED = 'passed'

PENDING = 'pending'

SKIPPED = 'skipped'

class yapcad.package.analysis.schema.SchemaError(path: str, message: str, severity: str = 'error')

Bases: object

Represents a schema validation error.

message: str

path: str

severity: str = 'error'

class yapcad.package.analysis.schema.ValidationKind(*values)

Bases: Enum

Supported validation test kinds.

ASSEMBLY = 'assembly'

CFD = 'cfd'

GEOMETRIC = 'geometric'

MEASUREMENT = 'measurement'

MULTIPHYSICS = 'multiphysics'

STRUCTURAL = 'structural'

THERMAL = 'thermal'

class yapcad.package.analysis.schema.ValidationReport(valid: bool, errors: List[SchemaError] = <factory>, warnings: List[SchemaError] = <factory>, schema_version: str = 'validation-schema-v0.1')

Bases: object

Result of schema validation.

errors: List[SchemaError]

schema_version: str = 'validation-schema-v0.1'

valid: bool

warnings: List[SchemaError]

yapcad.package.analysis.schema.validate_plan(data: Dict[str, Any]) → ValidationReport

Validate a validation plan against the schema.

Parameters:

data – The plan data as a dictionary (loaded from YAML)

Returns:

ValidationReport with validation results

yapcad.package.analysis.schema.validate_plan_file(path: str | Path) → ValidationReport

Validate a validation plan YAML file.

Parameters:

path – Path to the YAML file

Returns:

ValidationReport with validation results

yapcad.package.analysis.schema.validate_result(data: Dict[str, Any]) → ValidationReport

Validate a validation result against the schema.

Parameters:

data – The result data as a dictionary (loaded from JSON)

Returns:

ValidationReport with validation results

yapcad.package.analysis.schema.validate_result_file(path: str | Path) → ValidationReport

Validate a validation result JSON file.

Parameters:

path – Path to the JSON file

Returns:

ValidationReport with validation results

yapcad.package.analysis.yapcad_native module

Native yapCAD backend for geometric and measurement validation tests.

This module provides validation capabilities using yapCAD’s built-in geometry functions. No external solvers are required.

Supported test kinds: - geometric: volume, area, bbox checks - measurement: mass, centroid calculations

Usage:

from yapcad.package.analysis.yapcad_native import YapCADNativeAdapter

adapter = YapCADNativeAdapter() result = adapter.run(manifest, plan, workspace)

Copyright (c) 2025 yapCAD contributors MIT License

class yapcad.package.analysis.yapcad_native.YapCADNativeAdapter

Bases: AnalysisAdapter

Native yapCAD backend for geometric validation tests.

This adapter performs geometric and measurement checks using yapCAD’s built-in functions. It supports:

• Volume checks (solid volume against limits)

• Area checks (surface area or 2D region area)

• Bounding box checks (dimensions, diagonal)

• Mass checks (volume * density)

• Centroid checks (center of mass location)

Results include computed metrics and pass/fail status based on acceptance criteria.

name: str = 'yapcad'

run(manifest: Any, plan: AnalysisPlan, workspace: Path, **kwargs: Any) → AnalysisResult

Execute the validation check.

Parameters:

• manifest – Package manifest

• plan – Analysis plan specification

• workspace – Working directory for intermediate files

Returns:

AnalysisResult with metrics and pass/fail status

Module contents

Analysis helper exports.

class yapcad.package.analysis.AnalysisAdapter

Bases: ABC

Base class for solver adapters.

name: str = 'analysis-adapter'

abstractmethod run(manifest, plan: AnalysisPlan, workspace: Path, **kwargs: Any) → AnalysisResult

Execute the plan and return an AnalysisResult.

class yapcad.package.analysis.AnalysisPlan(plan_id: str, kind: str, backend: str, name: str | None = None, description: str | None = None, geometry: Dict[str, ~typing.Any]=<factory>, materials: Dict[str, ~typing.Any]=<factory>, loads: Dict[str, ~typing.Any]]=<factory>, boundary_conditions: Dict[str, ~typing.Any]]=<factory>, acceptance: Dict[str, ~typing.Any]=<factory>, backend_options: Dict[str, ~typing.Any]=<factory>, execution: ExecutionConfig = <factory>, attachments: Dict[str, ~typing.Any]]=<factory>, metadata: Dict[str, ~typing.Any]=<factory>, raw: Dict[str, ~typing.Any]=<factory>)

Bases: object

Representation of a validation/analysis plan loaded from YAML.

acceptance: Dict[str, Any]

attachments: List[Dict[str, Any]]

backend: str

backend_options: Dict[str, Any]

boundary_conditions: List[Dict[str, Any]]

description: str | None = None

execution: ExecutionConfig

geometry: Dict[str, Any]

kind: str

loads: List[Dict[str, Any]]

materials: Dict[str, Any]

metadata: Dict[str, Any]

name: str | None = None

property normalized_backend: str

plan_id: str

raw: Dict[str, Any]

class yapcad.package.analysis.AnalysisResult(plan_id: str, status: str, metrics: Dict[str, ~typing.Any]=<factory>, summary: Dict[str, ~typing.Any]=<factory>, artifacts: Dict[str, ~typing.Any]]=<factory>, summary_path: Path | None = None, backend: str | None = None, timestamp: str | None = None, notes: str | None = None)

Bases: object

Container for results emitted by analysis adapters.

artifacts: List[Dict[str, Any]]

backend: str | None = None

metrics: Dict[str, Any]

notes: str | None = None

plan_id: str

status: str

summary: Dict[str, Any]

summary_path: Path | None = None

timestamp: str | None = None

to_manifest_entry(package_root: Path) → Dict[str, Any]

class yapcad.package.analysis.ByAreaSelector(min_area: float | None = None, max_area: float | None = None, largest: bool = False, smallest: bool = False)

Bases: FaceSelector

Select faces by area criteria.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

set_context(faces: List[FaceInfo]) → None

Set all faces for largest/smallest comparison.

class yapcad.package.analysis.ByNormalSelector(direction: Tuple[float, float, float], tolerance_deg: float = 5.0, allow_reversed: bool = False)

Bases: FaceSelector

Select faces by normal direction.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

class yapcad.package.analysis.ByPositionSelector(axis: str = 'z', at_min: bool = False, at_max: bool = False, above: float | None = None, below: float | None = None, tolerance: float = 1e-06)

Bases: FaceSelector

Select faces by centroid position.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

set_context(faces: List[FaceInfo]) → None

Set all faces for min/max comparison.

class yapcad.package.analysis.CombinedSelector(selectors: List[FaceSelector], mode: str = 'and')

Bases: FaceSelector

Combine multiple selectors with AND/OR logic.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

set_context(faces: List[FaceInfo]) → None

Propagate context to child selectors.

class yapcad.package.analysis.ComparisonOp(*values)

Bases: Enum

Acceptance criteria comparison operators.

APPROX = '~='

EQ = '=='

GE = '>='

GT = '>'

LE = '<='

LT = '<'

class yapcad.package.analysis.ExecutionConfig(mode: str = 'local', command: str | None = None, transport: str | None = None, host: str | None = None, workdir: str | None = None, env: Dict[str, str]=<factory>, options: Dict[str, ~typing.Any]=<factory>, license: Dict[str, ~typing.Any]=<factory>)

Bases: object

Execution context for an analysis plan.

command: str | None = None

env: Dict[str, str]

host: str | None = None

property is_remote: bool

license: Dict[str, Any]

mode: str = 'local'

options: Dict[str, Any]

transport: str | None = None

workdir: str | None = None

class yapcad.package.analysis.FaceInfo(index: int, centroid: ~typing.Tuple[float, float, float], normal: ~typing.Tuple[float, float, float], area: float, name: str | None = None, tags: ~typing.List[str] = <factory>)

Bases: object

Information about a face for selection/naming.

index

Face index in the solid

Type:

int

centroid

Face centroid point

Type:

Tuple[float, float, float]

normal

Face normal vector (average for curved faces)

Type:

Tuple[float, float, float]

area

Face area

Type:

float

name

Optional assigned name

Type:

str | None

tags

Optional list of tags

Type:

List[str]

area: float

centroid: Tuple[float, float, float]

index: int

name: str | None = None

normal: Tuple[float, float, float]

tags: List[str]

class yapcad.package.analysis.FaceNamer(solid: Any)

Bases: object

Utility for naming faces of yapCAD solids.

This class extracts face information from solids and applies names based on selectors or explicit assignments.

property faces: List[FaceInfo]

Get list of face information.

get_named_faces() → Dict[str, List[int]]

Get all named faces.

Returns:

Mapping of names to face indices

name_faces(assignments: Dict[str, FaceSelector | List[int]]) → Dict[str, List[int]]

Apply face name assignments.

Parameters:

assignments – Mapping of names to selectors or explicit face indices

Returns:

Mapping of names to matched face indices

to_metadata() → Dict[str, Any]

Convert face naming to metadata format.

Returns:

Dictionary suitable for solid metadata

class yapcad.package.analysis.FaceSelector

Bases: object

Base class for face selection predicates.

matches(face: FaceInfo) → bool

Return True if face matches this selector.

class yapcad.package.analysis.GmshMesher(model_name: str = 'yapCAD_model')

Bases: object

Primary meshing interface using Gmsh’s OCC integration.

This class provides meshing capabilities for yapCAD solids using Gmsh. It leverages the shared OCC kernel between yapCAD and Gmsh for direct geometry transfer without intermediate file formats.

Example

mesher = GmshMesher() mesher.initialize() mesher.import_solid(solid) mesher.set_physical_groups({“fixed_face”: [1, 2], “load_face”: [3]}) mesher.generate_mesh(hints) mesher.export_mesh(Path(“output.msh”)) mesher.finalize()

export_mesh(path: Path, format: str | None = None) → Path

Export the mesh to a file.

Parameters:

• path – Output path

• format – Optional format override (msh, vtk, xdmf, su2)

Returns:

Path to the exported file

finalize() → None

Finalize Gmsh and release resources.

generate_mesh(hints: MeshHints | None = None, dim: int = 3) → None

Generate the mesh.

Parameters:

• hints – Mesh generation hints

• dim – Mesh dimension (2 for surface, 3 for volume)

get_mesh_stats() → Dict[str, Any]

Get mesh statistics.

Returns:

Dictionary with node count, element counts by type, quality metrics

import_solid(solid: Any, face_names: Dict[str, List[int]] | None = None, use_stl: bool = False) → List[Tuple[int, int]]

Import a yapCAD solid into Gmsh.

This uses Gmsh’s OCC integration to import the geometry directly from the OCC representation, avoiding STEP/IGES conversion losses.

Parameters:

• solid – yapCAD solid (must have OCC BREP representation)

• face_names – Optional mapping of face names to face indices

• use_stl – If True, use STL (tessellated) representation which may be more robust for complex geometries with topology issues

Returns:

List of (dim, tag) tuples for imported entities

import_step(step_path: Path) → List[Tuple[int, int]]

Import geometry from a STEP file.

Parameters:

step_path – Path to the STEP file

Returns:

List of (dim, tag) tuples for imported entities

initialize(verbose: bool = True, geometry_tolerance: float = 0.1) → None

Initialize Gmsh (must be called before other operations).

Parameters:

• verbose – If True, enable terminal output for progress monitoring

• geometry_tolerance – Tolerance for geometry repair operations

set_physical_groups(groups: Dict[str, List[int]], dim: int = 2) → None

Define physical groups for boundary conditions.

Physical groups associate mesh entities with names that can be used to apply boundary conditions in the solver.

Parameters:

• groups – Mapping of group names to entity tags

• dim – Dimension of entities (2 for faces, 3 for volumes)

set_physical_groups_by_normal(groups: Dict[str, Tuple[float, float, float]], tolerance_deg: float = 5.0) → None

Define physical groups by face normal direction.

This is useful for automatically identifying faces like “top”, “bottom”, “front”, etc. based on their orientation.

Parameters:

• groups – Mapping of group names to normal vectors (x, y, z)

• tolerance_deg – Angular tolerance in degrees

class yapcad.package.analysis.MeshHints(element_size: float = 5.0, min_element_size: float | None = None, max_element_size: float | None = None, algorithm_2d: int = 6, algorithm_3d: int = 1, element_order: int = 1, optimize: bool = True, optimize_netgen: bool = False, refinement_fields: Dict[str, ~typing.Any]]=<factory>, geometry_tolerance: float = 0.0001, recover_3d: bool = True, use_stl: bool = False, scale_factor: float = 1.0)

Bases: object

Mesh generation hints for Gmsh.

element_size

Target element size (mesh density)

Type:

float

min_element_size

Minimum element size

Type:

float | None

max_element_size

Maximum element size

Type:

float | None

algorithm_2d

2D meshing algorithm (1=MeshAdapt, 2=Auto, 5=Delaunay, 6=Frontal-Delaunay)

Type:

int

algorithm_3d

3D meshing algorithm (1=Delaunay, 4=Frontal, 10=HXT)

Type:

int

element_order

Element polynomial order (1=linear, 2=quadratic)

Type:

int

optimize

Whether to optimize mesh quality

Type:

bool

optimize_netgen

Use Netgen optimizer for 3D meshes

Type:

bool

refinement_fields

List of refinement field specifications

Type:

List[Dict[str, Any]]

geometry_tolerance

Tolerance for geometry healing (default 1e-4)

Type:

float

recover_3d

If False, skip 3D mesh generation and do 2D only

Type:

bool

stl_fallback

If True, use STL intermediate format when BREP fails

algorithm_2d: int = 6

algorithm_3d: int = 1

element_order: int = 1

element_size: float = 5.0

geometry_tolerance: float = 0.0001

max_element_size: float | None = None

min_element_size: float | None = None

optimize: bool = True

optimize_netgen: bool = False

recover_3d: bool = True

refinement_fields: List[Dict[str, Any]]

scale_factor: float = 1.0

use_stl: bool = False

class yapcad.package.analysis.PhysicalGroup(name: str, dim: int, tags: List[int])

Bases: object

A named group of mesh entities (for boundary conditions).

name

Human-readable name for the group

Type:

str

dim

Dimension (0=point, 1=edge, 2=face, 3=volume)

Type:

int

tags

Gmsh entity tags in this group

Type:

List[int]

dim: int

name: str

tags: List[int]

class yapcad.package.analysis.ResultStatus(*values)

Bases: Enum

Result status values.

ERROR = 'error'

FAILED = 'failed'

PASSED = 'passed'

PENDING = 'pending'

SKIPPED = 'skipped'

class yapcad.package.analysis.SchemaError(path: str, message: str, severity: str = 'error')

Bases: object

Represents a schema validation error.

message: str

path: str

severity: str = 'error'

class yapcad.package.analysis.ValidationKind(*values)

Bases: Enum

Supported validation test kinds.

ASSEMBLY = 'assembly'

CFD = 'cfd'

GEOMETRIC = 'geometric'

MEASUREMENT = 'measurement'

MULTIPHYSICS = 'multiphysics'

STRUCTURAL = 'structural'

THERMAL = 'thermal'

class yapcad.package.analysis.ValidationReport(valid: bool, errors: List[SchemaError] = <factory>, warnings: List[SchemaError] = <factory>, schema_version: str = 'validation-schema-v0.1')

Bases: object

Result of schema validation.

errors: List[SchemaError]

schema_version: str = 'validation-schema-v0.1'

valid: bool

warnings: List[SchemaError]

yapcad.package.analysis.available_backends() → Sequence[str]

yapcad.package.analysis.back_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with -Y normal (back faces).

yapcad.package.analysis.bottom_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with -Z normal (bottom faces).

yapcad.package.analysis.faces_at_z_max(tolerance: float = 1e-06) → ByPositionSelector

Select faces at maximum Z coordinate.

yapcad.package.analysis.faces_at_z_min(tolerance: float = 1e-06) → ByPositionSelector

Select faces at minimum Z coordinate.

yapcad.package.analysis.front_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with +Y normal (front faces).

yapcad.package.analysis.get_backend(name: str) → Type[AnalysisAdapter] | None

yapcad.package.analysis.gmsh_available() → bool

Return True if Gmsh Python API is available.

yapcad.package.analysis.largest_face() → ByAreaSelector

Select the largest face by area.

yapcad.package.analysis.left_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with -X normal (left faces).

yapcad.package.analysis.load_plan(path: Path | str) → AnalysisPlan

Load a YAML analysis plan and return the normalised AnalysisPlan.

yapcad.package.analysis.mesh_solid(solid: Any, output_path: Path, hints: MeshHints | None = None, physical_groups: Dict[str, List[int]] | None = None, dim: int = 3) → Dict[str, Any]

Convenience function to mesh a solid and export.

Parameters:

• solid – yapCAD solid to mesh

• output_path – Path for output mesh file

• hints – Mesh generation hints

• physical_groups – Optional face groups for BCs

• dim – Mesh dimension

Returns:

Mesh statistics dictionary

yapcad.package.analysis.register_backend(name: str, adapter_cls: Type[AnalysisAdapter]) → None

yapcad.package.analysis.right_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with +X normal (right faces).

yapcad.package.analysis.smallest_face() → ByAreaSelector

Select the smallest face by area.

yapcad.package.analysis.top_faces(tolerance_deg: float = 5.0) → ByNormalSelector

Select faces with +Z normal (top faces).

yapcad.package.analysis.validate_plan(data: Dict[str, Any]) → ValidationReport

Validate a validation plan against the schema.

Parameters:

data – The plan data as a dictionary (loaded from YAML)

Returns:

ValidationReport with validation results

yapcad.package.analysis.validate_plan_file(path: str | Path) → ValidationReport

Validate a validation plan YAML file.

Parameters:

path – Path to the YAML file

Returns:

ValidationReport with validation results

yapcad.package.analysis.validate_result(data: Dict[str, Any]) → ValidationReport

Validate a validation result against the schema.

Parameters:

data – The result data as a dictionary (loaded from JSON)

Returns:

ValidationReport with validation results

yapcad.package.analysis.validate_result_file(path: str | Path) → ValidationReport

Validate a validation result JSON file.

Parameters:

path – Path to the JSON file

Returns:

ValidationReport with validation results