Preprocessing: Beams

The anastruct.preprocess.beam module provides ready-made beam generators that automatically define nodes, elements, and supports for common structural configurations. Instead of building a model element by element with SystemElements, you instantiate a beam type and move straight to loading and analysis.

Importing

The beam module is available at the top level of the anastruct package:

from anastruct import beam

You can also import individual classes or the factory function directly:

from anastruct.preprocess.beam import SimpleBeam, MultiSpanBeam, create_beam

Once instantiated, every beam exposes its underlying SystemElements model as beam.system, giving access to the full suite of analysis and plotting methods.

Section properties

All beam constructors accept an optional section keyword — a dictionary describing the cross-section. The only required key is EI (bending stiffness); the remaining keys are filled with defaults if omitted:

• EI — bending stiffness (required; default 1e6 )

• EA — axial stiffness (optional; default 1e8 )

• g — distributed self-weight per unit length (optional; default 0.0 )

# Bending stiffness only — EA and g use defaults
b = beam.SimpleBeam(length=6.0, section={"EI": 8000})

# Fully specified
b = beam.SimpleBeam(length=6.0, section={"EI": 8000, "EA": 1.5e9, "g": 2.5})

If section is omitted entirely the beam uses the module defaults listed above.

Single-span beams

Simple beam

class anastruct.preprocess.beam.SimpleBeam(length, angle=0.0, section=None)

Simple beam with a pin support at one end, and a roller support at the other.

__init__(length, angle=0.0, section=None)

Initialize a beam structure.

Args:

length (float): Total length of the beam (length units). Must be positive.

Either length or span_lengths must be provided.

span_lengths (list[float]): List of span lengths for each span. Must be

positive. Either length or span_lengths must be provided.

angle (float): Angle of the beam (degrees; 0 = horizontal, positive = CCW);

defaults to 0.0

section (SectionProps): Section properties for all beam elements; defaults

to DEFAULT_BEAM_SECTION

Raises:

ValueError: If length or span_lengths are not positive, or if neither

(or both) are provided.

Cantilever beams

class anastruct.preprocess.beam.CantileverBeam(length, cantilever_side='right', angle=0.0, section=None)

Cantilever beam with a fixed support at one end and free at the other.

The cantilever_side parameter specifies which end is the free (unsupported) end. For example, cantilever_side="right" means the right end is free and the left end is fixed.

__init__(length, cantilever_side='right', angle=0.0, section=None)

Initialize a beam structure.

Args:

length (float): Total length of the beam (length units). Must be positive.

Either length or span_lengths must be provided.

span_lengths (list[float]): List of span lengths for each span. Must be

positive. Either length or span_lengths must be provided.

angle (float): Angle of the beam (degrees; 0 = horizontal, positive = CCW);

defaults to 0.0

section (SectionProps): Section properties for all beam elements; defaults

to DEFAULT_BEAM_SECTION

Raises:

ValueError: If length or span_lengths are not positive, or if neither

(or both) are provided.

RightCantileverBeam and LeftCantileverBeam are convenience subclasses that fix the free end without requiring a cantilever_side argument. Each accepts length, angle, and section only:

class anastruct.preprocess.beam.RightCantileverBeam(length, angle=0.0, section=None)

Cantilever beam with a fixed support at the left end and free (cantilevered) at the right.

class anastruct.preprocess.beam.LeftCantileverBeam(length, angle=0.0, section=None)

Cantilever beam with a free (cantilevered) left end and a fixed support at the right.

Multi-span beams

Multi-span beams are simply supported, placing a pin at the first support and rollers at all remaining supports. Spans may be equal or unequal.

class anastruct.preprocess.beam.MultiSpanBeam(length=None, num_spans=None, span_lengths=None, cantilevers=None, angle=0.0, section=None)

Simply supported multi-span beam. Assumes equal spans unless span_lengths provided.

__init__(length=None, num_spans=None, span_lengths=None, cantilevers=None, angle=0.0, section=None)

Initialize a beam structure.

Args:

length (float): Total length of the beam (length units). Must be positive.

Either length or span_lengths must be provided.

span_lengths (list[float]): List of span lengths for each span. Must be

positive. Either length or span_lengths must be provided.

angle (float): Angle of the beam (degrees; 0 = horizontal, positive = CCW);

defaults to 0.0

section (SectionProps): Section properties for all beam elements; defaults

to DEFAULT_BEAM_SECTION

Raises:

ValueError: If length or span_lengths are not positive, or if neither

(or both) are provided.

TwoSpanBeam, ThreeSpanBeam, and FourSpanBeam are convenience wrappers for equal-span multi-span beams. Each accepts length (the total length, which is divided equally), angle, and section:

class anastruct.preprocess.beam.TwoSpanBeam(length, angle=0.0, section=None)

Simply supported two-span beam with equal spans.

class anastruct.preprocess.beam.ThreeSpanBeam(length, angle=0.0, section=None)

Simply supported three-span beam with equal spans.

class anastruct.preprocess.beam.FourSpanBeam(length, angle=0.0, section=None)

Simply supported four-span beam with equal spans.

Propped beams

A propped beam has one interior simply supported span with a cantilever overhanging one end.

class anastruct.preprocess.beam.ProppedBeam(interior_length, cantilever_length, cantilever_side='right', angle=0.0, section=None)

Propped beam with an interior simple span and a cantilever on one side.

__init__(interior_length, cantilever_length, cantilever_side='right', angle=0.0, section=None)

Initialize a beam structure.

Args:

length (float): Total length of the beam (length units). Must be positive.

Either length or span_lengths must be provided.

span_lengths (list[float]): List of span lengths for each span. Must be

positive. Either length or span_lengths must be provided.

angle (float): Angle of the beam (degrees; 0 = horizontal, positive = CCW);

defaults to 0.0

section (SectionProps): Section properties for all beam elements; defaults

to DEFAULT_BEAM_SECTION

Raises:

ValueError: If length or span_lengths are not positive, or if neither

(or both) are provided.

RightProppedBeam and LeftProppedBeam are convenience subclasses that fix the overhang side. Each accepts interior_length, cantilever_length, angle, and section:

class anastruct.preprocess.beam.RightProppedBeam(interior_length, cantilever_length, angle=0.0, section=None)

Propped beam with an interior simple span and a cantilever on the right side.

class anastruct.preprocess.beam.LeftProppedBeam(interior_length, cantilever_length, angle=0.0, section=None)

Propped beam with an interior simple span and a cantilever on the left side.

Factory function

anastruct.preprocess.beam.create_beam(beam_type, **kwargs)

Factory function to create beam instances by type name.

Provides a convenient way to create beams without importing specific classes. Type names are case-insensitive and can use underscores or hyphens as separators.

Return type:

Beam

Args:

beam_type (str): The type of beam to create (e.g., “simple”, “cantilever”, “multi_span”) **kwargs: Arguments to pass to the beam constructor

Returns:

Beam: An instance of the requested beam type

Raises:

ValueError: If beam_type is not recognized

Examples:

>>> beam = create_beam("simple", length=10, section=section)
>>> beam = create_beam("cantilever", length=5, section=section)

Applying loads

All beam types share common load application methods. Loads can be applied across all spans at once, or restricted to a specific span or list of spans by passing a span index (0-indexed) via the spans argument:

Beam.apply_q_load_to_spans(q, direction='element', rotation=None, q_perp=None, spans=None)

Apply distributed load to all elements within one or more spans.

Return type:

None

Args:

q (Union[float, Sequence[float]]): Load magnitude (force/length units) direction (Union[LoadDirection, Sequence[LoadDirection]]): Load direction.

Options: “element”, “x”, “y”, “parallel”, “perpendicular”, “angle”

rotation (Optional[Union[float, Sequence[float]]]): Rotation angle in degrees

(used with direction=”angle”)

q_perp (Optional[Union[float, Sequence[float]]]): Perpendicular load component

Beam.apply_point_load_to_spans(Fx=0.0, Fy=0.0, rotation=0.0, absolute_location=None, relative_location=None, spans=None, tolerance=None)

Apply point load to elements within one or more spans.

Return type:

None

Args:

Fx (Union[float, Sequence[float]]): Horizontal load component (force units) Fy (Union[float, Sequence[float]]): Vertical load component (force units) rotation (Union[float, Sequence[float]]): Rotation angle in degrees absolute_location (Optional[float]): Absolute location along the beam length (length units).

Either absolute_location or relative_location must be provided.

relative_location (Optional[float]): Relative location along the beam length

(0.0 = start of span, 1.0 = end of span). Either absolute_location or relative_location must be provided.

spans (Optional[Union[int, Sequence[int]]]): Span(s) to apply the load to. If None,

applies to all spans.

tolerance (float): Tolerance for matching existing node locations (length units).

Defaults to beam length * 1e-4.

You can also apply loads directly through the underlying SystemElements object via beam.system, using the standard methods described in Loads.

Examples

Simply supported beam with a uniform distributed load

from anastruct import beam

# 6 m simply supported beam — only EI needs to be specified
b = beam.SimpleBeam(length=6.0, section={"EI": 8000})

# 10 kN/m downward load across the full span
b.apply_q_load_to_spans(q=-10)

b.system.solve()
b.show_structure()
b.system.show_bending_moment()
b.system.show_displacement()

Three-span beam with a point load on one span

Spans can be unequal by supplying span_lengths instead of length. The spans argument of the load methods targets individual spans by their 0-based index.

from anastruct import beam

# Spans of 4 m, 6 m, and 4 m — indexed 0, 1, 2
b = beam.MultiSpanBeam(span_lengths=[4.0, 6.0, 4.0], section={"EI": 12000})

# 50 kN concentrated load at the mid-point of the middle span (index 1)
b.apply_point_load_to_spans(Fy=-50, relative_location=0.5, spans=1)

# 2 kN/m dead load on all spans
b.apply_q_load_to_spans(q=-2)

b.system.solve()
b.system.show_bending_moment()
b.system.show_reaction_force()