pycba.results.Envelopes#

class Envelopes(vResults)[source]#

Bases: object

Envelopes load effects from a vector of BeamResults.

x#

Coordinates along the beam.

Type:: np.ndarray

Vmax, Vmin

Maximum and minimum shear force envelopes.

Type:: np.ndarray

Mmax, Mmin

Maximum and minimum bending moment envelopes.

Type:: np.ndarray

Vco_Mmax#

Shear coincident with the moment maximum at each point.

Type:: np.ndarray

Vco_Mmin#

Shear coincident with the moment minimum at each point.

Type:: np.ndarray

Mco_Vmax#

Moment coincident with the shear maximum at each point.

Type:: np.ndarray

Mco_Vmin#

Moment coincident with the shear minimum at each point.

Type:: np.ndarray

Rmax, Rmin

Reaction history matrices (nsup x nres).

Type:: np.ndarray

Rmaxval, Rminval

Maximum and minimum reaction per support.

Type:: np.ndarray

Constructs the envelope of each load effect given a vector of results for the beam. Also tracks coincident (co-existing) load effects: the value of the other effect (V or M) at the analysis that caused each envelope extreme.

Parameters:: vResults (List[MemberResults]) – The vector of results from each analysis that are to be enveloped.
Return type:: None.

Methods

`at`	Return envelope values at a global coordinate by interpolation.
`augment`	Augments this set of envelopes with another compatible set, making this the envelopes of the two sets of envelopes.
`combine`	Merge several compatible envelopes into a new `Envelopes`.
`from_beam_analysis`	Build a single-result `Envelopes` from one analysed beam.
`per_span`	Split a station-indexed envelope array into per-span values.
`plot`	Plots the envelopes of bending and shear.
`plot_coincidents`	Plot each load-effect envelope together with the coincident value of the other effect, grouped by which extreme drives them.
`sum`	Adds another compatible set of envelopes to this one element-wise.
`to_csv`	Write the envelopes (an `x` column plus each requested attribute) to a CSV file with `numpy.savetxt()` (no pandas needed).
`to_dataframe`	Return the envelopes as a `pandas.DataFrame` with an `x` column and one column per requested envelope attribute (default the moment and shear extremes).
`zero_like`	Returns a zeroed zet of envelopes like the reference `pycba.results.Envelopes`.

classmethod zero_like(env)[source]#

Returns a zeroed zet of envelopes like the reference pycba.results.Envelopes. This is necessary since a pycba.results.Envelopes object stores information about the beam from which it came. This facilitates the creation of an envelope of envelopes.

Parameters:: env (Envelopes) – A pycba.results.Envelopes to be used as the basis for a zeroed pycba.results.Envelopes object.
Returns:: A pycba.results.Envelopes object of zero-valued envelopes.
Return type:: Envelopes

classmethod combine(envs, mode='envelope')[source]#

Merge several compatible envelopes into a new Envelopes.

This is a one-call replacement for the zero_like + repeated augment()/sum() ritual. The input envelopes are left unmutated; a fresh Envelopes is returned.

Parameters:

envs (Sequence[Envelopes]) – One or more compatible pycba.results.Envelopes objects (same npts and nsup). All must come from the same beam geometry.
mode (str) – "envelope" (default) takes the governing maxima/minima of moment and shear (plus coincident effects and reaction extremes) by calling augment() for each input. "sum" superimposes the envelopes element-wise by calling sum() for each input.

Returns:

A new merged pycba.results.Envelopes object.

Return type:

Envelopes

Raises:

ValueError – If envs is empty or mode is not "envelope" or "sum".

Notes

When the merged envelopes come from analyses with differing numbers of results (nres), only the reaction extremes (Rmaxval/Rminval) are retained; the per-analysis reaction history is zeroed. This is the pre-existing behaviour of augment()/sum().

classmethod from_beam_analysis(ba)[source]#

Build a single-result Envelopes from one analysed beam.

This is the discoverable adapter that lifts an ordinary pycba.analysis.BeamAnalysis result (for example the result of a pycba.load_cases.LoadCombination.analyze() call) into a first-class pycba.results.Envelopes, so it can be merged with combine() or the |/+ operators and plotted.

Parameters:: ba (BeamAnalysis) – An analysed beam whose beam_results are available.
Returns:: A one-result pycba.results.Envelopes.
Return type:: Envelopes
Raises:: ValueError – If ba has not been analysed (ba.beam_results is None).

augment(env)[source]#

Augments this set of envelopes with another compatible set, making this the envelopes of the two sets of envelopes. Coincident values are updated to match whichever envelope governs at each point.

All envelopes must be from the same pycba.bridge.BridgeAnalysis object.

If the envelopes have a different number of analyses (due to differing vehicle lengths, for example), then only the reaction extreme are retained, and not the entire reaction history.

Parameters:: env (Envelopes) – A compatible pycba.results.Envelopes object.
Raises:: ValueError – All envelopes must be for the same bridge.
Return type:: None.

sum(env)[source]#

Adds another compatible set of envelopes to this one element-wise. This is useful for superimposing load effects from different sources, e.g. a patterned UDL envelope with a moving vehicle envelope.

All envelopes must be for the same beam geometry.

If the envelopes have a different number of analyses (due to differing vehicle lengths, for example), then only the reaction extremes are retained, and not the entire reaction history.

Parameters:: env (Envelopes) – A compatible pycba.results.Envelopes object.
Raises:: ValueError – All envelopes must be for the same beam geometry.
Return type:: None.

__add__(other)[source]#

Superposition of self and other (non-mutating).

a + b is sugar for Envelopes.combine([a, b], mode="sum") and returns a new Envelopes with the two operands summed element-wise. Neither operand is mutated.

Note that this differs from sum(), which mutates in place and returns None.

Return type:: Envelopes

at(x, attrs=('Mmax', 'Mmin', 'Vmax', 'Vmin'))[source]#

Return envelope values at a global coordinate by interpolation.

The station array self.x repeats span-boundary coordinates (each span contributes its own start and end), so this method de-duplicates the stations with numpy.unique() before interpolating. It replaces the manual idx = (np.abs(env.x - x)).argmin() lookup.

Parameters:

x (float) – Global coordinate measured from the left end of the beam.
attrs (Tuple[str, ...]) – Envelope attribute names to evaluate. The default returns the moment and shear extremes.

Returns:

Mapping from each requested attribute name to its interpolated value at x.

Return type:

Dict[str, float]

to_dataframe(attrs=('Mmax', 'Mmin', 'Vmax', 'Vmin'))[source]#: Return the envelopes as a pandas.DataFrame with an x column and one column per requested envelope attribute (default the moment and shear extremes). Requires pandas.

to_csv(path, attrs=('Mmax', 'Mmin', 'Vmax', 'Vmin'), **kwargs)[source]#: Write the envelopes (an x column plus each requested attribute) to a CSV file with numpy.savetxt() (no pandas needed). Returns path.

per_span(attr='Mmax', reduce='auto')[source]#

Split a station-indexed envelope array into per-span values.

The station array concatenates each member’s stations, so this method chunks the requested attribute using the per-member station counts read from self.vResults[0].vRes (each member’s x length, i.e. npts + 3) rather than a hard-coded constant. It replaces the manual env.Vmax[i * (n + 3):(i + 1) * (n + 3)] slicing.

Parameters:

attr (str) – Envelope attribute name to split (default "Mmax").
reduce (str) – How to reduce each per-span chunk. "auto" (default) takes the maximum for *max attributes and the minimum for *min attributes; "max"/"min" force the reduction; "none" returns the list of raw chunks.

Returns:

One reduced value per span, or the list of raw chunks when reduce="none".

Return type:

ndarray

Raises:

ValueError – If reduce is not one of "auto", "max", "min", "none".

plot(each=False, units=None, backend=None, **kwargs)[source]#

Plots the envelopes of bending and shear.

Parameters:

each (Boolean) – Wether or not to show each BMD and SFD in the enveloping. The default is False
units (str or pycba.units.UnitSystem, optional) – Display unit system for the labels (see pycba.set_units()).
backend ({"matplotlib", "plotly"}, optional) – Plotting backend; defaults to the global default (see pycba.set_backend()). With "plotly" an interactive, hover-to-read envelope figure (a plotly.graph_objects.Figure) is returned, with the max/min band shaded; each and **kwargs do not apply.
**kwargs (Dict) – Matplotlib keyword arguments for plotting.

Return type:

None.

plot_coincidents(units=None, show=True, figsize=(10, 6))[source]#

Plot each load-effect envelope together with the coincident value of the other effect, grouped by which extreme drives them.

For combined-action checks at a section you need not the extreme of one effect but the value of the other effect at the vehicle position that produced it. Two panels share the distance axis, each with dual y-axes (so both quantities are solid lines on their own scale):

the moment panel — the moment envelope Mmax/Mmin (left axis) and the shear that coexists with those moment extremes, Vco_Mmax/Vco_Mmin (right axis);
the shear panel — the shear envelope Vmax/Vmin (left axis) and the moment that coexists with those shear extremes, Mco_Vmax/Mco_Vmin (right axis).

Parameters:

units (str or pycba.units.UnitSystem, optional) – Display unit system for the labels (see pycba.set_units()).
show (bool) – Call matplotlib.pyplot.show() before returning (default True).
figsize (tuple(float, float), optional) – Figure size in inches.

Returns:

matplotlib.figure.Figure
numpy.ndarray of matplotlib.axes.Axes – The two primary (left-axis) panel axes; the coincident (right-axis) twins are reachable via fig.axes.