Skip to content

compas_timber.structural ¤

Classes¤

BeamSegmentGenerator ¤

Base class for beam segment generators.

Subclasses should implement generate_segments to produce structural segments for a beam, given its joints.

Used by:

Functions¤

generate_segments abstractmethod ¤
generate_segments(beam: Beam, joints: Sequence[Joint]) -> list[StructuralSegment]

Generate structural segments for a beam.

Parameters:

  • beam (:class:`compas_timber.elements.Beam`) –

    The beam for which to generate segments.

  • joints (list of :class:`compas_timber.connections.Joint`) –

    The joints associated with the beam.

Returns:

  • list of :class:`StructuralSegment` –

BeamStructuralElementSolver ¤

BeamStructuralElementSolver(
    beam_segment_generator: BeamSegmentGenerator | None = None,
    joint_connector_generator: JointConnectorGenerator | None = None,
    interaction_type: InteractionType | None = None,
)

Produces structural segments for beams and joints in a timber model.

Parameters:

  • beam_segment_generator (:class:`BeamSegmentGenerator`, default: None ) –

    Generator used to produce structural segments for beams. Defaults to :class:SimpleBeamSegmentGenerator.

  • joint_connector_generator (:class:`JointConnectorGenerator`, default: None ) –

    Generator used to produce connector segments for joints. Defaults to :class:SimpleJointConnectorGenerator.

  • interaction_type (:class:`InteractionSource`, default: None ) –

    Which interaction types to consider when creating structural segments. Defaults to InteractionSource.AUTO.

Functions¤

add_joint_structural_segments ¤
add_joint_structural_segments(
    model: TimberModel, joints: Iterable[Joint]
) -> Iterable[StructuralSegment]

Creates and adds structural segments for a given joint to the timber model.

For joints connecting non-intersecting beams (e.g. crossing beams), this creates a 'virtual' element connecting the centerlines of the beams.

Parameters:

  • model (:class:`compas_timber.model.TimberModel`) –

    The timber model containing the beams and joints.

  • joints (iterable of :class:`compas_timber.connections.Joint`) –

    The joints for which to create structural segments.

Returns:

  • list of :class:`StructuralSegment` –

    The structural segments that were created and added to the model.

add_structural_segments ¤
add_structural_segments(
    model: TimberModel,
) -> tuple[list[StructuralSegment], Iterable[Joint]]

Creates and adds structural segments for a given beam to the timber model.

These are essentially segments of the beam's centerline split at the locations of the joints.

Parameters:

  • model (:class:`compas_timber.model.TimberModel`) –

    The timber model containing the beams and joints.

Returns:

  • list of :class:`StructuralSegment` –

    The structural segments that were created and added to the model.

  • set of :class:`compas_timber.connections.Joint` –

    The joints that were traversed when creating the structural segments. This is the definitive set of joints traversed when creating the beam segments, and should be used when creating joint connector segments to avoid duplicates.

InteractionType ¤

Defines which interaction types to consider when creating structural segments.

Attributes:

  • AUTO (int) –

    Per connection: use joints if available, fall back to candidates.

  • JOINTS (int) –

    Only use joints, ignore candidates.

  • CANDIDATES (int) –

    Only use candidates, ignore joints.

Used by:

JointConnectorGenerator ¤

Base class for joint connector segment generators.

Subclasses should implement generate_connectors to produce structural connector segments for a joint.

Used by:

Functions¤

generate_connectors abstractmethod ¤
generate_connectors(joint: Joint) -> list[tuple[Beam, Beam, list[StructuralSegment]]]

Generate connector segments for a joint.

Parameters:

  • joint (:class:`compas_timber.connections.Joint`) –

    The joint for which to generate connector segments.

Returns:

  • list of tuple(Beam, Beam, list of :class:`StructuralSegment`) –

    Each tuple contains the two beams being connected and the connector segments between them.

SimpleBeamSegmentGenerator ¤

Generates structural segments by splitting the beam centerline at joint locations.

SimpleJointConnectorGenerator ¤

Generates connector segments as virtual lines between non-intersecting beam centerlines.

StructuralGraph ¤

StructuralGraph(*args, **kwargs)

A structural graph derived from a :class:~compas_timber.model.TimberModel.

Wraps a :class:~compas.datastructures.Graph and provides a domain-specific API so callers never need to touch raw graph attributes directly.

Nodes are unique structural points (DOF locations — the endpoints of all structural segments, deduplicated within tolerance). Edges are the structural segments themselves, each tagged as either "beam" or "connector" and carrying a back-reference to the originating timber model element.

Create instances via :meth:from_model rather than directly.

Attributes:

  • nodes (iterator) –

    The node keys of all nodes in the graph.

  • edges (iterator) –

    All (u, v) edge pairs in the graph.

  • beam_edges (iterator) –

    (u, v) pairs for edges that represent beam-centerline segments.

  • connector_edges (iterator) –

    (u, v) pairs for edges that represent virtual connector segments between non-intersecting beam centerlines.

Examples:

>>> sg = StructuralGraph.from_model(model)
>>> for u, v in sg.beam_edges:
...     pt_i = sg.node_point(u)
...     pt_j = sg.node_point(v)
...     seg = sg.segment(u, v)
...     beam = sg.beam(u, v)
>>> for u, v in sg.connector_edges:
...     joint = sg.joint(u, v)
>>> segs = sg.segments_for_beam(my_beam)
Returned by:

Attributes¤

beam_edges property ¤
beam_edges

Iterate over (u, v) pairs for all beam-segment edges.

connector_edges property ¤
connector_edges

Iterate over (u, v) pairs for all connector-segment edges.

Functions¤

beam ¤
beam(u, v)

Return the source :class:~compas_timber.elements.Beam for a beam edge.

Parameters:

  • u (int, graph node) –
  • v (int, graph node) –

Returns:

  • class:`~compas_timber.elements.Beam` or None –

    None for connector edges.

from_model classmethod ¤
from_model(model: TimberModel) -> StructuralGraph

Builds a :class:StructuralGraph from the structural segments stored in a timber model.

Nodes represent unique endpoints of structural segments (identified within tolerance). Edges represent the segments themselves. Each edge carries:

  • segment — the :class:StructuralSegment;
  • type — "beam" or "connector";
  • beam — (beam edges) the source :class:~compas_timber.elements.Beam;
  • joint — (connector edges) the source :class:~compas_timber.connections.Joint, or None when the connector was derived from a candidate rather than a resolved joint.

Parameters:

  • model (:class:`~compas_timber.model.TimberModel`) –

    The timber model whose structural segments are used to build the graph.

Returns:

  • class:`StructuralGraph` –

Raises:

  • ValueError –

    If no structural segments are found in the model. Call :meth:~compas_timber.model.TimberModel.create_beam_structural_segments first.

Examples:

>>> model.create_beam_structural_segments()
>>> sg = StructuralGraph.from_model(model)
>>> for u, v in sg.beam_edges:
...     print(sg.node_index(u), sg.node_index(v), sg.segment(u, v).line.length, sg.beam(u, v).name)
joint ¤
joint(u, v)

Return the source :class:~compas_timber.connections.Joint for a connector edge.

Parameters:

  • u (int, graph node) –
  • v (int, graph node) –

Returns:

  • class:`~compas_timber.connections.Joint` or None –

    None for beam edges or when the connector was derived from a candidate rather than a resolved joint.

node_index ¤
node_index(node)

Return the sequential integer index of node.

The index is stable for the lifetime of this object and is suitable for building connectivity tables (e.g. for exporting to FEM software).

Parameters:

  • node (object) –

    A node key as returned by iterating :attr:nodes.

Returns:

node_point ¤
node_point(node)

Return the 3-D position of a node as a :class:~compas.geometry.Point.

Parameters:

  • node (object) –

    A node key as returned by iterating :attr:nodes.

Returns:

  • class:`~compas.geometry.Point` –
segment ¤
segment(u, v)

Return the :class:StructuralSegment on the edge (u, v).

Parameters:

  • u (int, graph node) –
  • v (int, graph node) –

Returns:

  • class:`StructuralSegment` –
segments_for_beam ¤
segments_for_beam(beam)

Return all (u, v) beam edges that belong to beam.

Parameters:

  • beam (:class:`~compas_timber.elements.Beam`) –

Returns:

  • list of tuple(u, v) –
segments_for_joint ¤
segments_for_joint(joint)

Return all (u, v) connector edges that were generated for joint.

Parameters:

  • joint (:class:`~compas_timber.connections.Joint`) –

Returns:

  • list of tuple(u, v) –