structural-lib-is456

IS 456 reinforced-concrete design library (Python package).

Version: 0.25.0 (normal/final version format; publication state is in the release ledger) Status:

⚠️ Pre-1.0 API: APIs may change until v1.0. For reproducible results, pin to an exact release.

Supported-case boundary: this package implements selected IS 456 workflows, not the whole standard. Every output requires independent verification and qualified structural-engineering review. Use official standards as the authoritative source.

New in v0.25.0

• Member input readiness: native beam-readiness/v1 evidence binds explicit physical intent, support and ULS/SLS roles to the exact ledger, source and engine. The public Python API preserves ready, provisional, missing, unsupported and failed outcomes without converting input readiness into engineering approval.
• Reproducible delivery: the public member-readiness example distinguishes stored evidence from current bindings and rejects stale or altered inputs.
• Cumulative supported-case improvements: complete ordinary/multilayer worked members, physical reinforcement/anchorage repairs, supported column/flange/SLS corrections and issued-amendment solid-slab/staircase fixes are included.
• Scope: complete nonzero-torsion member admission remains held; existing component torsion operations and the 13 family-facade journeys remain distinct.

Retained capabilities from v0.24.0

• Fail-closed project intake: malformed, missing, unknown, or mixed-validity beam rows block the whole project instead of being defaulted or skipped.
• Safe public CLI: design keeps JSON on stdout, sends diagnostics to stderr, exits non-zero on blocked input, and preserves the bbs/detail/dxf chain.
• Traceable results: import ledgers, input/result provenance, API classification, and qualified-review boundaries are explicit and machine-readable.
• Additional bounded workflows: braced walls, straight-flight staircases, simply supported deep beams, regular interior flat slabs, symmetric combined footings, and property-line strap footings expose case-qualified APIs.
• Release verification matrix: exact-wheel UAT exercises 29 positive and negative cases, 15 CLI entries, and the 13 canonical family construction journeys.

Install

After the release ledger confirms publication of the selected version:

pip install structural-lib-is456==0.25.0         # exact normal release
pip install "structural-lib-is456[dxf]==0.25.0"  # release with DXF export
python -m structural_lib install-preflight          # interpreter/origin/extras

0.25.0 has a normal/final package version and is eligible for selection without --pre after publication. Confirm public artifact availability in the release ledger. The Beta maturity classifier and the explicit limitations above remain: broader library development and cumulative practicing-engineer review are still in progress.

Requires Python 3.11+. On Python 3.9–3.10, pip installs the older v0.16.x (beam-only, no column/footing).

Choosing an API

For supported element design/checks, use structural_lib.design.is456. For explicit physical beam reinforcement, analysis and project workflows, see structural_lib.beam and the source repository's docs/library/getting-started.md. Existing root and api imports remain supported compatibility routes.

The current source adds typed family group imports, typed calculation results, slab input_* builders, and direct JSON loaders such as beam.load_json. JSON loaders reject ambiguous duplicate fields and return structured input errors. Run Python/examples/canonical_workflows.py after pip install -e ./Python from the repository root. These additions have not been published as a new release; the install commands above retain their exact published-version meaning.

The same source build provides typed operation outputs and result-bound physical-member/candidate workflows. Run Python/examples/physical_member_workflow.py for project → checks → physical paths → quantities/package data, and Python/examples/candidate_ranking_workflow.py for ranking genuine calculations. Those teaching profiles state their limited engineering scope and retain missing, failed and stale outcomes.

If You Want To…

Design and Detail a Beam Through the Canonical Facade

from structural_lib.design.is456 import beam

detailing = beam.BeamDetailingOptionsV1(
    standard=beam.DetailingStandard.IS456,
    clear_cover_mm=40,
    tension_bar_diameter_mm=20,
    compression_bar_diameter_mm=16,
    nominal_top_steel_ratio=0.25,
    stirrup_diameter_mm=8,
    stirrup_legs=2,
    stirrup_spacing_support_mm=150,
    stirrup_spacing_mid_mm=200,
)
request = beam.input(
    member_id="B1",
    story="GF",
    case_id="ULS-1",
    span_mm=5000,
    b_mm=300,
    D_mm=550,
    d_mm=492,
    fck_nmm2=25,
    fy_nmm2=500,
    mu_knm=150,
    vu_kn=80,
    d_dash_mm=56,
    asv_mm2=detailing.asv_mm2,
    detailing=detailing,
    source_provenance="analysis-envelope:ULS-1",
)
result = beam.design_and_detail(
    request,
    detailing_standard=beam.DetailingStandard.IS456,
)

print(result.engineering_status)
print(result.to_dict())

The example uses d = 550 - 40 - 8 - 20/2 = 492 mm and d_dash = 40 + 8 + 16/2 = 56 mm, matching the stated reinforcement.

The complete 13-journey cookbook is maintained at docs/cookbook/python/family-facades.md in the source repository.

Generate a Bar Bending Schedule (BBS)

bbs = beam.bbs(result)
print(f"Total weight: {bbs.total_weight_kg:.1f} kg")
for item in bbs.items:
    print(f"  {item.bar_mark}: ø{item.diameter_mm:.0f} × {item.no_of_bars} nos")

Use the Compact Compatibility Beam-to-BBS Route

The canonical facade is recommended for new integrations. The retained structural_lib.api facade remains useful for existing scripts and quick evaluations:

from structural_lib import api

result = api.design_and_detail_beam_is456(
    units="IS456", beam_id="B1", story="GF",
    span_mm=5500, mu_knm=160, vu_kn=85, b_mm=300, D_mm=500, d_mm=444,
)
print(result.summary())
bbs = api.compute_bbs(result)
print(f"BBS weight: {bbs.summary.total_weight_kg:.1f} kg")

The example depth is 500 - 40 - 8 - 16/2 = 444 mm, matching the generated single-layer 16 mm tension bars. Combined design/detailing rejects mismatched depths and multiple-layer layouts whose row centroids are not defined. Use explicit supplied reinforcement when layer positions are needed.

Identity names differ on two retained service functions: design_and_detail_beam_is456() uses beam_id; the lower-level design_beam_is456() service uses case_id.

Export DXF Drawings and Reports

Use the fail-closed CLI pipeline for project files and exports:

python -m structural_lib design input.csv -o results.json
python -m structural_lib detail results.json -o detailing.json
python -m structural_lib bbs results.json -o schedule.csv
python -m structural_lib dxf results.json -o drawings.dxf
python -m structural_lib report results.json --format=html -o report.html

Requires the dxf extra: pip install "structural-lib-is456[dxf]"

Generic CSV imports preserve optional effective depth from d_mm, d (mm), d, eff_d, effective_depth_mm or Effective Depth. Overall D and effective d are distinct columns. Supplied depth must be finite and satisfy 0 < d < D; it survives Python model serialization, API import and saved-project restoration. When depth is omitted, the existing explicit depth-basis workflow still applies. An explicit analysis depth does not establish that generated reinforcement fits; design-to-detailing checks continue to verify that separately.

Batch Design with the Canonical Project Schema

from structural_lib.services.batch import design_project_beams_v1

batch = design_project_beams_v1(
    [
        {
            "schema_version": "project-beam-design/v1",
            "member_id": "B1",
            "b_mm": 300,
            "D_mm": 500,
            "d_mm": 442,
            "mu_knm": 150,
            "vu_kn": 100,
            "fck_nmm2": 25,
            "fy_nmm2": 500,
        }
    ]
)
print(batch.summary.to_dict())
print(batch.members[0].calculation["flexure"]["ast_required"])

Run the Full Pipeline (design → detail → BBS → report)

See examples/end_to_end_workflow.py for a complete working script (available in the source repository).

The compatibility adapter retains design_inputs, the original case and the result envelope. compute_detailing() checks that geometry, materials, bar centroids and stirrups match the passing source design. Default stirrup spacing respects the calculated maximum; explicit excessive spacing is rejected. Failed designs remain reportable but cannot produce design-derived schedules. Regenerate older design JSON that lacks design_inputs before using detail, bbs or dxf. Explicit steel-only drafting inputs do not establish strength acceptance. The CLI's unmodified span/depth screen remains supported for the same geometry. Supplied reinforcement factors, crack strains and torsion need their documented canonical detailing scope and evidence.

Cost-Optimize a Beam

from structural_lib import optimize_beam_cost

optimized = optimize_beam_cost(
    units="IS456", span_mm=6000, mu_knm=150, vu_kn=100,
)
print(f"Optimal: {optimized.optimal_design.b_mm}×{optimized.optimal_design.D_mm} mm")

Check Multi-Case Compliance

from structural_lib import check_beam_is456

report = check_beam_is456(
    units="IS456", b_mm=230, D_mm=500, d_mm=450,
    fck_nmm2=25, fy_nmm2=500,
    cases=[{"case_id": "ULS-1", "mu_knm": 100, "vu_kn": 80}],
)
print(f"Governing case: {report.governing_case_id}")

CLI Usage

The design command is fail-closed. CSV input must explicitly supply BeamID,Story,b,D,eff_d,Span,Cover,fck,fy,Mu,Vu,Stirrup_Dia,Stirrup_Spacing. Instead of eff_d, supply tension_bar_diameter_mm so effective depth can be derived from the explicit cover and stirrup diameter. JSON input uses the cli-beam-design-input/v1 envelope. Unknown, duplicate, malformed, non-finite, empty, ambiguous, or mixed-validity input blocks the whole project without a partial result.

python -m structural_lib design input.csv -o results.json        # Beam design
python -m structural_lib bbs results.json -o bbs.csv             # Bar bending schedule
python -m structural_lib dxf results.json -o drawings.dxf        # DXF drawings
python -m structural_lib report results.json --format=html -o report.html  # HTML report
python -m structural_lib job job.json -o output/                 # Full job from spec
python -m structural_lib --help                                  # All options

What's Available

Beam Design & Detailing

The primary combined beam route covers flexure and shear. Torsion is available only through the separate explicit torsion workflow.

Column Design (IS 456 Cl 25, 39.3–39.7)

Footing Design (IS 456 Cl 34)

The low-level functions in this section cover isolated footings. Separate canonical facades cover bounded symmetric combined-footing and property-line strap-footing cases; use their generated recipes to see every required assumption and evidence field. Raft and pile-cap foundations, settlement, geotechnical design, and lateral stability remain outside the supported routes.

Solid Slab Design (Supported Cases)

The canonical two-way facade uses the library's bounded normalized coefficient lookup and interpolation for supported common panels. Compatibility functions that accept caller-supplied coefficients remain separate and require explicit source approval. Drop/ribbed slabs, openings, irregular panels, concentrated loads, and FEM remain outside the solid-slab route; use the separate regular interior flat-slab facade only for its documented bounded case.

IS 13920 Ductile Detailing

Export, Import & Visualization

Full API reference: see the online API reference.

License

MIT — see the repository license.

Engineering-use conditions and professional responsibilities are described in the repository's engineering-use conditions. The software is a design aid, not a substitute for official code publications, independent calculation, or professional approval.