gensec.output

Plotting, numerical export, and terminal reporting.

All output functions accept section and solver objects directly and adapt to the section type (generic polygon or legacy rectangular). Rebar layers are numbered sequentially (1-based), and this numbering is consistent across terminal output, plots, and CSV exports.

Plotting

Plotting utilities for N-M diagrams, section state maps, and demand analysis.

All section state plots (strain, stress) are drawn as coloured maps on the actual section geometry. Rebar values are annotated directly on the section, replacing numbered labels.

Supports both rectangular and arbitrary polygon sections via the polygon attribute from GenericSection.

plot_3d_surface(
nm_3d,
demands=None,
title='',
n_levels=20,
n_angles=72,
)

Plot the 3D resistance surface as a lofted surface built from Mx-My contour slices at regular N intervals.

Two side-by-side perspective views are generated: one from above (compression-dominant) and one from below (tension-dominant, N axis visually inverted).

Contour rings (“parallels”) and meridian lines (“longitudes”) are drawn on the surface to aid shape comprehension.

Parameters:

  • nm_3d (dict) – Output of NMDiagram.generate_biaxial(). Must contain N_kN, Mx_kNm, My_kNm.

  • demands (list of dict, optional)

  • title (str, optional)

  • n_levels (int, optional) – Number of N-level slices. Default 20.

  • n_angles (int, optional) – Angular resolution of each contour. Default 72 (every 5°).

Return type:

matplotlib.figure.Figure

plot_demand_heatmap(
check_results,
title='',
)

Grouped horizontal bar chart of all enabled utilization ratios.

Each demand gets one bar per \(\eta\) type present in the results. Bars exceeding 1.0 are coloured red; those within the limit are green.

Parameters:

  • check_results (list of dict) – Output of VerificationEngine.check_demands().

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_from_json(
filepath,
output_path=None,
dpi=150,
)

Regenerate a plot from a previously exported JSON data file.

Detects the data type from the "type" key in the JSON and dispatches to the appropriate plotting function.

Supported types:

For files without a "type" key, the function inspects the available keys to infer the data type (N-M domain, 3-D surface, demand summary, etc.).

Parameters:

  • filepath (str) – Path to JSON data file.

  • output_path (str or None) – Output PNG path. If None, derived from the JSON filename.

  • dpi (int, optional) – Resolution. Default 150.

Returns:

Path of the generated PNG file.

Return type:

str

Raises:

ValueError – If the data type cannot be determined.

plot_moment_curvature(
mc_data,
title='',
)

Plot the moment-curvature diagram with cracking, yield and ultimate markers and a numerical legend.

Parameters:

  • mc_data (dict)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_moment_curvature_bundle(
mc_list,
direction='x',
title='',
)

Plot a family of moment-curvature curves at different axial force levels on the same axes.

Each curve is coloured by its N value using a sequential colourmap, providing an immediate view of how ductility and moment capacity change with axial force.

Parameters:

  • mc_list (list of dict) – Each dict is the output of NMDiagram.generate_moment_curvature() at a different N_fixed.

  • direction ('x' or 'y', optional) – Default 'x'.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_moment_curvature_surface(
mc_list,
direction='x',
title='',
)

3D surface of moment vs curvature vs axial force.

The individual M-χ curves are interpolated onto a common χ grid and rendered as a continuous surface using plot_surface().

Parameters:

  • mc_list (list of dict) – Each dict is the output of NMDiagram.generate_moment_curvature().

  • direction ('x' or 'y', optional)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_mx_my_diagram(
mx_my_data,
demands=None,
title='',
)

Plot the Mx-My interaction contour at fixed N.

Parameters:

  • mx_my_data (dict)

  • demands (list of tuple, optional)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_nm_diagram(
nm_data,
demands=None,
title='',
)

Plot the N-M interaction diagram with convex hull boundary.

Parameters:

  • nm_data (dict)

  • demands (list of tuple, optional) – (N_kN, M_kNm, label) demand points.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_polar_ductility(
nm_gen,
N_fixed,
n_angles=72,
n_points=400,
title='',
)

Polar diagram of ultimate curvature as a function of bending direction.

For each angle \(\theta\) in the \((\chi_x, \chi_y)\) plane, the section is loaded to failure at the given axial force. The radial coordinate is the ultimate curvature magnitude \(\chi_u(\theta)\).

A circular plot means isotropic ductility; elongation along one axis reveals higher ductility in that bending direction.

The scan uses warm-starting: the equilibrium eps0 from the previous angle is carried over as initial guess, which greatly improves convergence smoothness.

Parameters:

  • nm_gen (NMDiagram) – The diagram generator (wraps solver).

  • N_fixed (float) – Axial force [N].

  • n_angles (int, optional) – Angular resolution. Default 72.

  • n_points (int, optional) – Curvature steps per direction. Default 400.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_section(
sec,
fiber_results=None,
title='',
)

Draw the cross-section geometry with rebars.

If fiber_results are provided, draws a two-panel figure: left = geometry with numbered rebars + neutral axis, right = stress field.

Parameters:

  • sec (GenericSection or RectSection)

  • fiber_results (dict, optional)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_section_state(
sec,
fiber_results,
field='eps',
title='',
)

Draw the section with a colour-mapped field (strain or stress).

Each bulk fiber is drawn as a coloured scatter point. Rebar values are annotated directly on the section instead of sequential numbers. The neutral axis is drawn extending beyond the section on both sides.

Parameters:

  • sec (GenericSection or RectSection)

  • fiber_results (dict) – Output of FiberSolver.get_fiber_results().

  • field ('eps' or 'sigma') – Which field to plot. Default 'eps'.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_stress_profile(
results,
sec,
title='',
)

Legacy wrapper — now generates two section-state maps (strain and stress) side by side.

Parameters:

  • results (dict)

  • sec (GenericSection or RectSection)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

CSV and JSON export

Numerical export utilities — CSV and JSON.

Provides functions to export N-M domain points, demand verification results, and per-fiber stress/strain states.

export_3d_surface_csv(
nm_3d,
filepath,
)

Export 3D resistance surface (N, Mx, My) to CSV.

Parameters:

  • nm_3d (dict) – Output of NMDiagram.generate_biaxial().

  • filepath (str)

export_3d_surface_json(
nm_3d,
filepath,
)

Export 3D resistance surface (N, Mx, My) to JSON.

Parameters:

  • nm_3d (dict) – Output of NMDiagram.generate_biaxial().

  • filepath (str)

export_combination_results_json(
results,
filepath,
)

Export combination verification results to JSON.

Handles both simple and staged combinations per the v2.1 spec.

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_combination() calls.

  • filepath (str)

export_demand_results_csv(
results,
filepath,
)

Export demand verification summary to CSV (v2.1 format).

Columns include all enabled \(\eta\) types.

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_demands().

  • filepath (str)

export_demand_results_json(
results,
filepath,
)

Export demand verification summary to JSON (v2.1 format).

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_demands().

  • filepath (str)

export_envelope_results_json(
results,
filepath,
)

Export envelope verification results to JSON.

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_envelope() calls.

  • filepath (str)

export_fiber_results_csv(
fiber_results,
filepath,
)

Export per-fiber strain/stress state to CSV.

Two sections in the file: BULK and REBARS, separated by a blank line.

Parameters:

  • fiber_results (dict) – Output of FiberSolver.get_fiber_results().

  • filepath (str)

export_moment_curvature_csv(
mc_data,
filepath,
)

Export moment-curvature curve to CSV.

Parameters:

  • mc_data (dict)

  • filepath (str)

export_moment_curvature_json(
mc_data,
filepath,
)

Export moment-curvature data to JSON.

The JSON contains the full curve arrays plus all key points (cracking, yield, ultimate), sufficient to regenerate the plot via gensec plot.

Parameters:

  • mc_data (dict) – Output of NMDiagram.generate_moment_curvature().

  • filepath (str)

export_mx_my_csv(
mx_my_data,
filepath,
)

Export Mx-My interaction contour to CSV.

Parameters:

  • mx_my_data (dict)

  • filepath (str)

export_mx_my_json(
mx_my_data,
filepath,
)

Export Mx-My interaction contour to JSON.

Parameters:

  • mx_my_data (dict) – Output of NMDiagram.generate_mx_my().

  • filepath (str)

export_nm_domain_csv(
nm_data,
filepath,
)

Export N-M domain point cloud to CSV.

Columns: N_kN, Mx_kNm.

Parameters:

  • nm_data (dict) – Output of NMDiagram.generate().

  • filepath (str) – Output CSV file path.

export_nm_domain_json(
nm_data,
filepath,
)

Export N-M domain point cloud to JSON.

Parameters:

  • nm_data (dict) – Output of NMDiagram.generate().

  • filepath (str) – Output JSON file path.

export_verification_json(
demand_results,
combination_results,
envelope_results,
filepath,
)

Export the complete verification summary to a single JSON file.

Parameters:

  • demand_results (list of dict)

  • combination_results (list of dict)

  • envelope_results (list of dict)

  • filepath (str)

Terminal reporting

Text reporting utilities.

All rebar layers are numbered sequentially (1-based) and this numbering is consistent across terminal output, plots, and CSV exports.

Supports both GenericSection and legacy RectSection.

print_fiber_results(
results,
sec,
)

Print strain and stress at rebars and sampled bulk fibers.

Parameters:

  • results (dict) – Output of FiberSolver.get_fiber_results().

  • sec (GenericSection or RectSection)

print_section_info(
sec,
)

Print a formatted summary of section properties.

Adapts to the section type: shows bounding box dimensions, gross area, mesh method and quality for generic sections; shows B x H and grid resolution for rectangular sections.

Parameters:

sec (GenericSection or RectSection)

Package-level exports

Output subpackage — reporting, plotting, and numerical export.

export_3d_surface_csv(
nm_3d,
filepath,
)

Export 3D resistance surface (N, Mx, My) to CSV.

Parameters:

  • nm_3d (dict) – Output of NMDiagram.generate_biaxial().

  • filepath (str)

export_3d_surface_json(
nm_3d,
filepath,
)

Export 3D resistance surface (N, Mx, My) to JSON.

Parameters:

  • nm_3d (dict) – Output of NMDiagram.generate_biaxial().

  • filepath (str)

export_combination_results_json(
results,
filepath,
)

Export combination verification results to JSON.

Handles both simple and staged combinations per the v2.1 spec.

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_combination() calls.

  • filepath (str)

export_demand_results_csv(
results,
filepath,
)

Export demand verification summary to CSV (v2.1 format).

Columns include all enabled \(\eta\) types.

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_demands().

  • filepath (str)

export_demand_results_json(
results,
filepath,
)

Export demand verification summary to JSON (v2.1 format).

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_demands().

  • filepath (str)

export_envelope_results_json(
results,
filepath,
)

Export envelope verification results to JSON.

Parameters:

  • results (list of dict) – Output of VerificationEngine.check_envelope() calls.

  • filepath (str)

export_fiber_results_csv(
fiber_results,
filepath,
)

Export per-fiber strain/stress state to CSV.

Two sections in the file: BULK and REBARS, separated by a blank line.

Parameters:

  • fiber_results (dict) – Output of FiberSolver.get_fiber_results().

  • filepath (str)

export_moment_curvature_csv(
mc_data,
filepath,
)

Export moment-curvature curve to CSV.

Parameters:

  • mc_data (dict)

  • filepath (str)

export_moment_curvature_json(
mc_data,
filepath,
)

Export moment-curvature data to JSON.

The JSON contains the full curve arrays plus all key points (cracking, yield, ultimate), sufficient to regenerate the plot via gensec plot.

Parameters:

  • mc_data (dict) – Output of NMDiagram.generate_moment_curvature().

  • filepath (str)

export_mx_my_csv(
mx_my_data,
filepath,
)

Export Mx-My interaction contour to CSV.

Parameters:

  • mx_my_data (dict)

  • filepath (str)

export_mx_my_json(
mx_my_data,
filepath,
)

Export Mx-My interaction contour to JSON.

Parameters:

  • mx_my_data (dict) – Output of NMDiagram.generate_mx_my().

  • filepath (str)

export_nm_domain_csv(
nm_data,
filepath,
)

Export N-M domain point cloud to CSV.

Columns: N_kN, Mx_kNm.

Parameters:

  • nm_data (dict) – Output of NMDiagram.generate().

  • filepath (str) – Output CSV file path.

export_nm_domain_json(
nm_data,
filepath,
)

Export N-M domain point cloud to JSON.

Parameters:

  • nm_data (dict) – Output of NMDiagram.generate().

  • filepath (str) – Output JSON file path.

export_verification_json(
demand_results,
combination_results,
envelope_results,
filepath,
)

Export the complete verification summary to a single JSON file.

Parameters:

  • demand_results (list of dict)

  • combination_results (list of dict)

  • envelope_results (list of dict)

  • filepath (str)

plot_3d_surface(
nm_3d,
demands=None,
title='',
n_levels=20,
n_angles=72,
)

Plot the 3D resistance surface as a lofted surface built from Mx-My contour slices at regular N intervals.

Two side-by-side perspective views are generated: one from above (compression-dominant) and one from below (tension-dominant, N axis visually inverted).

Contour rings (“parallels”) and meridian lines (“longitudes”) are drawn on the surface to aid shape comprehension.

Parameters:

  • nm_3d (dict) – Output of NMDiagram.generate_biaxial(). Must contain N_kN, Mx_kNm, My_kNm.

  • demands (list of dict, optional)

  • title (str, optional)

  • n_levels (int, optional) – Number of N-level slices. Default 20.

  • n_angles (int, optional) – Angular resolution of each contour. Default 72 (every 5°).

Return type:

matplotlib.figure.Figure

plot_demand_heatmap(
check_results,
title='',
)

Grouped horizontal bar chart of all enabled utilization ratios.

Each demand gets one bar per \(\eta\) type present in the results. Bars exceeding 1.0 are coloured red; those within the limit are green.

Parameters:

  • check_results (list of dict) – Output of VerificationEngine.check_demands().

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_from_json(
filepath,
output_path=None,
dpi=150,
)

Regenerate a plot from a previously exported JSON data file.

Detects the data type from the "type" key in the JSON and dispatches to the appropriate plotting function.

Supported types:

For files without a "type" key, the function inspects the available keys to infer the data type (N-M domain, 3-D surface, demand summary, etc.).

Parameters:

  • filepath (str) – Path to JSON data file.

  • output_path (str or None) – Output PNG path. If None, derived from the JSON filename.

  • dpi (int, optional) – Resolution. Default 150.

Returns:

Path of the generated PNG file.

Return type:

str

Raises:

ValueError – If the data type cannot be determined.

plot_moment_curvature_bundle(
mc_list,
direction='x',
title='',
)

Plot a family of moment-curvature curves at different axial force levels on the same axes.

Each curve is coloured by its N value using a sequential colourmap, providing an immediate view of how ductility and moment capacity change with axial force.

Parameters:

  • mc_list (list of dict) – Each dict is the output of NMDiagram.generate_moment_curvature() at a different N_fixed.

  • direction ('x' or 'y', optional) – Default 'x'.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_moment_curvature_surface(
mc_list,
direction='x',
title='',
)

3D surface of moment vs curvature vs axial force.

The individual M-χ curves are interpolated onto a common χ grid and rendered as a continuous surface using plot_surface().

Parameters:

  • mc_list (list of dict) – Each dict is the output of NMDiagram.generate_moment_curvature().

  • direction ('x' or 'y', optional)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_mx_my_diagram(
mx_my_data,
demands=None,
title='',
)

Plot the Mx-My interaction contour at fixed N.

Parameters:

  • mx_my_data (dict)

  • demands (list of tuple, optional)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_nm_diagram(
nm_data,
demands=None,
title='',
)

Plot the N-M interaction diagram with convex hull boundary.

Parameters:

  • nm_data (dict)

  • demands (list of tuple, optional) – (N_kN, M_kNm, label) demand points.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_polar_ductility(
nm_gen,
N_fixed,
n_angles=72,
n_points=400,
title='',
)

Polar diagram of ultimate curvature as a function of bending direction.

For each angle \(\theta\) in the \((\chi_x, \chi_y)\) plane, the section is loaded to failure at the given axial force. The radial coordinate is the ultimate curvature magnitude \(\chi_u(\theta)\).

A circular plot means isotropic ductility; elongation along one axis reveals higher ductility in that bending direction.

The scan uses warm-starting: the equilibrium eps0 from the previous angle is carried over as initial guess, which greatly improves convergence smoothness.

Parameters:

  • nm_gen (NMDiagram) – The diagram generator (wraps solver).

  • N_fixed (float) – Axial force [N].

  • n_angles (int, optional) – Angular resolution. Default 72.

  • n_points (int, optional) – Curvature steps per direction. Default 400.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_section_state(
sec,
fiber_results,
field='eps',
title='',
)

Draw the section with a colour-mapped field (strain or stress).

Each bulk fiber is drawn as a coloured scatter point. Rebar values are annotated directly on the section instead of sequential numbers. The neutral axis is drawn extending beyond the section on both sides.

Parameters:

  • sec (GenericSection or RectSection)

  • fiber_results (dict) – Output of FiberSolver.get_fiber_results().

  • field ('eps' or 'sigma') – Which field to plot. Default 'eps'.

  • title (str, optional)

Return type:

matplotlib.figure.Figure

plot_stress_profile(
results,
sec,
title='',
)

Legacy wrapper — now generates two section-state maps (strain and stress) side by side.

Parameters:

  • results (dict)

  • sec (GenericSection or RectSection)

  • title (str, optional)

Return type:

matplotlib.figure.Figure

print_fiber_results(
results,
sec,
)

Print strain and stress at rebars and sampled bulk fibers.

Parameters:

  • results (dict) – Output of FiberSolver.get_fiber_results().

  • sec (GenericSection or RectSection)

print_section_info(
sec,
)

Print a formatted summary of section properties.

Adapts to the section type: shows bounding box dimensions, gross area, mesh method and quality for generic sections; shows B x H and grid resolution for rectangular sections.

Parameters:

sec (GenericSection or RectSection)