pycba.beam.Beam

class Beam(L=None, EI=None, R=None, LM=None, eletype=None, D=None, supports=None, GAv=None, kf=None)

Bases: object

A continuous beam: its members, supports and loads.

A beam is built from one or more members — each a two-node Euler–Bernoulli (or, with GAv, Timoshenko) element of given length and EI — added with add_member() (or the older add_span()).

Member vs span. A member is the element between two adjacent nodes; a clear span is the distance between two supports. In the common case the two coincide, but a clear span may be modelled with several members (e.g. to place an intermediate node, a load discontinuity or an internal hinge), so no_members counts the elements, not the supported spans.

Constructs a beam object

Parameters:

• L (Optional[ndarray]) – A vector of member lengths (one per member; a clear span between supports may comprise several members).

• EI (Optional[ndarray]) – A vector of member flexural rigidities.

• R (Optional[ndarray]) – A vector describing the support conditions at each member end (the low-level restraint vector). Provide either R or the friendlier supports, not both.

• LM (Optional[List[List[Union[int, float]]]]) – The load matrix: a list of loads on the beam; each load with several parameters.

• eletype (Optional[ndarray]) – A vector of the member types, each an integer code 1-4, a MemberType, or a name string ("FF"/"FP"/ "PF"/"PP"). Defaults to a fixed-fixed element.

• D (Optional[ndarray]) – A vector of prescribed displacements. Must have same length as R. Use None for DOFs without prescribed displacement.

• supports (Optional[Sequence[Union[str, Sequence[float]]]]) – A friendlier alternative to R: one entry per node (left to right), each a support name ("p"/"pin"/"pinned", "r"/"roller", "e"/"encastre"/"fixed", "f"/"free") or a raw [vertical, rotation] DOF pair (e.g. [5e4, 0] for a vertical spring). Lowered to R via supports_to_R(). Mutually exclusive with R.

• GAv (Union[float, SectionEI, Sequence, None]) – Transverse shear rigidity G·A_v of each span (A_v the shear area). A span with a finite GAv is analysed as a shear-deformable Timoshenko element; None (the default) keeps the member on the exact Euler–Bernoulli path, bit-for-bit unchanged. Like EI: a single scalar (or one SectionEI describing GAv(x)) applies to all spans, otherwise one entry per span (each None, a scalar, or a SectionEI).

• kf (Union[float, Sequence, None]) – Winkler foundation modulus (modulus of subgrade reaction per unit beam length). A span with a finite kf rests on an elastic (Winkler) foundation, modelled as a statically-condensed beam-on-elastic-foundation super-element; None (default) leaves the span unsupported by a foundation. A scalar applies to all spans, otherwise one entry per span.

Return type:

None.

Methods

add_load	Adds a new load to the beam's load matrix
add_member	Add a member (span) to the beam, naming its type.
add_span	Add a span to the continuous beam
get_local_span_coords	Returns the span index and position in span for a position given in global coordinates on the beam
get_ref	Returns Released End Forces for the member; that is, the Consistent Nodal Loads modified for the element type (i.e. releases).
get_span_k	Returns the stiffness matrix for the ith span
k_FF	Stiffness matrix for a fixed-fixed element
k_FF_timo	Stiffness matrix for a prismatic fixed-fixed Timoshenko element.
k_FP	Stiffness matrix for a fixed-pinned element
k_PF	Stiffness matrix for a pinned-fixed element
k_PP	Stiffness matrix for a pinned-pinned element
k_nonprismatic	4x4 stiffness matrix of a non-prismatic (variable-EI) element.
k_theta	2x2 moment-rotation stiffness of the (chord-relative) element ends.
k_timoshenko	4x4 Timoshenko element stiffness for scalar or variable EI/GAv.
plot	Draw a structural schematic of the beam.
save_tikz	Write the TikZ/stanli source to path (and optionally compile it).
to_tikz	Generate a TikZ/stanli representation of the beam.

Attributes

length	returns: length -- The total length of the beam :rtype: float
loads	Returns the load matrix for the beam
no_fixed_restraints	Returns the number of fixed restraints of the beam (fully-supported DOFs)
no_members	The number of members in the beam.
no_restraints	Returns the number of restraints of the beam
no_spans	Deprecated alias of no_members.
prescribed_displacements	Returns the prescribed displacements vector for the beam
restraints	Returns the restraints vector for the beam
structure_version	A counter that increments whenever the beam structure changes.

add_span(L, EI, eletype=1, GAv=None, kf=None)

Add a span to the continuous beam

Parameters:

• L (float) – The length of the member.

• EI (float) – The flexural rigidity of the member.

• eletype (Union[int, str, MemberType]) – The element type for the member, as the integer code 1-4, a MemberType (e.g. MemberType.FP), or its case-insensitive name (e.g. "FP"). See MemberType.

• GAv (Union[float, SectionEI, None]) – Transverse shear rigidity G·A_v of the member. When given (and finite) the member is a shear-deformable Timoshenko element; None (default) keeps the exact Euler–Bernoulli element. A SectionEI describes a variable GAv(x).

• kf (Optional[float]) – Winkler foundation modulus. When given, the member rests on an elastic (Winkler) foundation (prismatic, fixed-fixed, no GAv).

Return type:

None.

add_member(L, EI, mbr_type=MemberType.FF, GAv=None, kf=None)

Add a member (span) to the beam, naming its type.

A friendlier alias of add_span() whose mbr_type accepts a MemberType, a name string ("FF"/"FP"/"PF"/ "PP"), or the integer code 1-4.

Parameters:

• L (float) – The length of the member.

• EI (float) – The flexural rigidity of the member.

• mbr_type (Union[int, str, MemberType]) – The member type / moment-release pattern (default FF).

• GAv (Union[float, SectionEI, None]) – Transverse shear rigidity G·A_v; when given the member is a shear-deformable Timoshenko element (see add_span()).

• kf (Optional[float]) – Winkler foundation modulus; when given the member rests on an elastic (Winkler) foundation (see add_span()).

property loads: List[List[int | float]]

Returns the load matrix for the beam

Returns:

LM – The load matrix for the beam

Return type:

LoadMatrix

add_load(load)

Adds a new load to the beam’s load matrix

Parameters:

load (List[Union[int, float]]) – A list describing the load to be added

Return type:

None

property restraints: ndarray

Returns the restraints vector for the beam

Returns:

_restraints – The restraints vector for the beam

Return type:

np.ndarray

property structure_version: int

A counter that increments whenever the beam structure changes.

Bumped by changes to geometry, rigidity, restraints or prescribed displacements (but not loads). Used to invalidate a cached stability check (see pycba.analysis.BeamAnalysis.is_stable()).

Type:

int

property prescribed_displacements: list

Returns the prescribed displacements vector for the beam

Returns:

_prescribed_displacements – The prescribed displacements vector for the beam

Return type:

list

property no_members

The number of members in the beam.

A member is an element between two nodes; a clear span (the distance between two supports) may comprise several members (e.g. to place an intermediate node, load discontinuity or internal hinge).

Returns:

no_members

Return type:

int

property no_spans

Deprecated alias of no_members.

property no_restraints

Returns the number of restraints of the beam

Returns:

no_restraints – The number of restraints in the beam

Return type:

int

property no_fixed_restraints

Returns the number of fixed restraints of the beam (fully-supported DOFs)

Returns:

no_fixed_restraints – The number of fixed restraints in the beam

Return type:

int

property length

returns: length – The total length of the beam :rtype: float

get_local_span_coords(pos)

Returns the span index and position in span for a position given in global coordinates on the beam

Parameters:

pos (float) – The position of interest in global coordinates along the length of the beam

Return type:

(int, float)

Returns:

• ispan (int) – The index (1-based) of the span in which the point of interest falls

• pos_in_span (float) – The local coordinate along the member of the point of interest

plot(loads=None, *, tikz=None, ax=None, save=None, compile=False, load_cases=None, **kwargs)

Draw a structural schematic of the beam.

By default this renders with matplotlib; saving to a .tex path (or passing tikz=True) produces publication-quality TikZ/stanli output instead. The beam structure (geometry, supports, internal hinges) is always drawn; the loads layer is optional and its source is selected with loads:

• None (default) - the beam’s own load matrix self.LM.

• [] - draw the bare structure only.

• a PyCBA load matrix, a LoadCase, or a LoadCombination (supply its LoadCases via load_cases).

Parameters:

• loads (list | LoadCase | LoadCombination, optional) – The load source to draw.

• tikz (bool, optional) – Backend selector. None (default) infers it from save: a .tex target renders TikZ/stanli; anything else (or no save) renders with matplotlib. Pass True/False to force the backend - e.g. tikz=True to return the LaTeX source, or to render an otherwise-ambiguous .pdf target via TikZ.

• ax (matplotlib.axes.Axes, optional) – Axes to draw into (matplotlib backend only); a new figure is created if omitted.

• save (str or pathlib.Path, optional) – If given, also write the visualisation to this path; the file extension selects the backend when tikz is None. A .tex target writes the TikZ/stanli source; any other extension is saved by matplotlib (format inferred from the extension, e.g. .png/.pdf/.svg). Under the TikZ backend a .pdf target is compiled with pdflatex.

• compile (bool) – Under the TikZ backend with save set, run pdflatex to also produce a PDF (requires a LaTeX install with stanli). A .pdf save target enables this automatically. Ignored for the matplotlib backend.

• load_cases (pycba.load_cases.LoadCases, optional) – Required only when loads is a LoadCombination.

• **kwargs – Forwarded to the backend renderer: pycba.render.BeamPlotter.render_mpl() (dimensions, labels, load_values, color, units) or, when tikz=True, pycba.render.BeamPlotter.render_tikz() (standalone, scale, dimensions, labels, load_values, units). units selects the display unit system (see pycba.set_units()).

Returns:

• matplotlib.axes.Axes – The axes drawn into (matplotlib backend).

• str – The LaTeX source, when the TikZ backend is selected and save is not given.

• pathlib.Path – The written file, when the TikZ backend is selected with save (the .tex path, or the .pdf when compiled).

to_tikz(loads=None, *, load_cases=None, **kwargs)

Generate a TikZ/stanli representation of the beam.

Loads are selected with loads exactly as for plot().

Parameters:

• loads (list | LoadCase | LoadCombination, optional) – The load source to draw.

• load_cases (pycba.load_cases.LoadCases, optional) – Required only when loads is a LoadCombination.

• **kwargs – Forwarded to pycba.render.BeamPlotter.render_tikz() (standalone, scale, dimensions, labels, load_values).

Returns:

The LaTeX source.

Return type:

str

save_tikz(path, loads=None, *, compile=False, load_cases=None, **kwargs)

Write the TikZ/stanli source to path (and optionally compile it).

Loads are selected with loads exactly as for plot().

Parameters:

• path (str or pathlib.Path) – Output .tex path.

• loads (list | LoadCase | LoadCombination, optional) – The load source to draw.

• compile (bool) – If True, run pdflatex to also produce a PDF (requires a LaTeX install with the stanli package).

• load_cases (pycba.load_cases.LoadCases, optional) – Required only when loads is a LoadCombination.

Returns:

The .tex path, or the produced .pdf when compile=True.

Return type:

pathlib.Path

get_ref(i_span)

Returns Released End Forces for the member; that is, the Consistent Nodal Loads modified for the element type (i.e. releases)

Parameters:

ispan (int) – The index (1-based) of the span in which the point of interest falls

Returns:

ref – The totalled CNL object for the member, considering all loads.

Return type:

LoadCNL

get_span_k(i_span)

Returns the stiffness matrix for the ith span

Parameters:

ispan (int) – The index (1-based) of the span in which the point of interest falls

Returns:

kb – The stiffness matrix for the member

Return type:

ndarray

k_FF(EI, L)

Stiffness matrix for a fixed-fixed element

Parameters:

• EI (float) – The flexural rigidity for the member (assumed prismatic)

• L (float) – The length of the member

Returns:

k – The stiffness matrix for the member

Return type:

ndarray

k_FP(EI, L)

Stiffness matrix for a fixed-pinned element

Parameters:

• EI (float) – The flexural rigidity for the member (assumed prismatic)

• L (float) – The length of the member

Returns:

k – The stiffness matrix for the member

Return type:

ndarray

k_PF(EI, L)

Stiffness matrix for a pinned-fixed element

Parameters:

• EI (float) – The flexural rigidity for the member (assumed prismatic)

• L (float) – The length of the member

Returns:

k – The stiffness matrix for the member

Return type:

ndarray

k_PP(EI, L)

Stiffness matrix for a pinned-pinned element

Parameters:

• EI (float) – The flexural rigidity for the member (assumed prismatic)

• L (float) – The length of the member

Returns:

k – The stiffness matrix for the member

Return type:

ndarray

k_theta(EI, L)

2x2 moment-rotation stiffness of the (chord-relative) element ends.

This is the inverse of the rotational flexibility matrix (see _flexibility()), relating the end moments [M_i, M_j] to the chord-relative end rotations [theta_i, theta_j].

Parameters:

• EI (SectionEI) – The variable-rigidity description of the member.

• L (float) – The length of the member.

Returns:

The end moment-rotation stiffness matrix K_theta = F^-1.

Return type:

ndarray

k_nonprismatic(EI, L, eType)

4x4 stiffness matrix of a non-prismatic (variable-EI) element.

The 2x2 moment-rotation stiffness K_theta from flexibility integration (see k_theta()) is expanded to the full 4-DOF element using the kinematic transformation that removes the rigid-body chord rotation psi = (v_j - v_i)/L:

\[\begin{split}\begin{bmatrix} \theta_i \\ \theta_j \end{bmatrix} = T \begin{bmatrix} v_i \\ \theta_i \\ v_j \\ \theta_j \end{bmatrix}, \quad T = \begin{bmatrix} 1/L & 1 & -1/L & 0 \\ 1/L & 0 & -1/L & 1 \end{bmatrix}\end{split}\]

so the element stiffness is k = T^T K_theta T. The end shears emerge automatically as (M_i + M_j)/L from this transformation, matching PyCBA’s DOF order [v_i, theta_i, v_j, theta_j] and sign convention.

Moment releases (element types 2, 3, 4) are imposed by static condensation of the released rotational DOF(s), exactly mirroring the prismatic k_FP(), k_PF(), and k_PP(): the released row/column are zeroed and their flexibility is condensed out.

For a constant EI(x) this reproduces the closed-form prismatic k_FF(), k_FP(), k_PF(), k_PP() to machine precision.

Parameters:

• EI (SectionEI) – The variable-rigidity description of the member.

• L (float) – The length of the member.

• eType (int) – The element type (1: FF, 2: FP, 3: PF, 4: PP).

Returns:

k – The element stiffness matrix.

Return type:

ndarray

k_FF_timo(EI, GAv, L)

Stiffness matrix for a prismatic fixed-fixed Timoshenko element.

The standard two-node shear-flexible element introduces the dimensionless shear parameter

\[\Phi = \frac{12 EI}{G A_v L^2}\]

so the element stiffness is

\[\begin{split}k = \frac{EI}{(1+\Phi)L^3} \begin{bmatrix} 12 & 6L & -12 & 6L \\ 6L & (4+\Phi)L^2 & -6L & (2-\Phi)L^2 \\ -12 & -6L & 12 & -6L \\ 6L & (2-\Phi)L^2 & -6L & (4+\Phi)L^2 \end{bmatrix}\end{split}\]

As GAv -> inf (\Phi -> 0) this reduces exactly to the Euler–Bernoulli k_FF(). The DOF order and sign convention match the rest of PyCBA, [v_i, theta_i, v_j, theta_j], with theta the cross-section rotation.

Parameters:

• EI (float) – The flexural rigidity of the member (assumed prismatic).

• GAv (float) – The transverse shear rigidity G·A_v of the member.

• L (float) – The length of the member.

Returns:

k – The element stiffness matrix.

Return type:

ndarray

k_timoshenko(EI, GAv, L, eType)

4x4 Timoshenko element stiffness for scalar or variable EI/GAv.

The 2x2 moment-rotation stiffness K_theta (the inverse of the shear-augmented flexibility, see _timo_flexibility()) is expanded to the full 4-DOF element by the same kinematic chord transformation used for the non-prismatic element (see k_nonprismatic()), and moment releases (element types 2, 3, 4) are imposed by static condensation. This single path covers prismatic and non-prismatic, constant- and variable-shear members; for a constant EI/GAv it reproduces k_FF_timo() (and hence the Euler–Bernoulli element as GAv -> inf) to machine precision.

Parameters:

• EI (Union[float, SectionEI]) – The flexural rigidity (constant or variable).

• GAv (Union[float, SectionEI]) – The shear rigidity (constant or variable).

• L (float) – The length of the member.

• eType (int) – The element type (1: FF, 2: FP, 3: PF, 4: PP).

Returns:

k – The element stiffness matrix.

Return type:

ndarray