springcalc

A Python library for spring calculations: compression, extension, and torsion springs. Includes material data, wire characteristic calculations, and fatigue analysis via the Goodman diagram.

Visit the library in my guithub https://github.com/ErnestoAvedillo/springcalc and clone my repository using:

git clone git@github.com:ErnestoAvedillo/springcalc.git

Structure

src/springcalc/         Library package
├── lineal/             Calculation engine (compression, extension, torsion, Goodman,
│                       3D visualization, progressive-compression animation)
├── pymodels/           Data models (pydantic): material, units, wire, positions
├── material/           Material and tolerance tables (CSV, package data)
├── regresiones/        Fitted models loaded at runtime
│   └── factor_f/       Shigley's factor f (plain JSON coefficients + loader)
├── plots/              Goodman diagram generation
└── report/             PDF report generation (SpringPDFReport)

tests/                  Tests (pytest)
scripts/regresiones/    Training scripts that regenerate the JSON coefficients (not runtime)
docs/                   Reference material (spreadsheet, figures)

Installation

I recommend to use uv to install the library (https://docs.astral.sh/uv/):

# create the environment and install dependencies
uv init
uv add springcalc

Usage

from springcalc import Material, CompressionSpring

material = Material(material_name="SH")
spring = CompressionSpring(material=material, wire_diameter=1.0)
spring.set_geometry(outer_diameter=10.0, free_length=50.0, nr_coils=10)
properties = compression_spring.get_spring_data()
    for key, value in properties.items():
        print(f"{key}: {value}")                       )

Generating a PDF report (spring data, load/travel/diameter curves, and the Goodman fatigue diagram):

from springcalc.report import SpringPDFReport

report = SpringPDFReport(spring, title="Spring XYZ-123")
report.build("spring_report.pdf")

API Reference

• Material data — Material, get_available_materials()
• Wire characteristics — WireCharacteristics
• Compression springs — CompressionSpring
• Extension springs — ExtensionSpring
• Torsion springs — TorsionSpring
• Fatigue analysis (Goodman diagram) — GoodmanData, GoodmanAnalyzer, Goodman, generate_goodman_diagram()
• Position tables — LinearPositionsTable, AngularPositionsTable
• PDF reports — SpringPDFReport
• Advanced: variable-geometry springs — VariableLinealSpring, CompressionSpringGeneral
• Animating progressive compression — CompressionAnimator

All physical quantities are pint Quantity objects (a number with a unit, e.g. 20.0 millimeter). Plain numbers passed into a field are usually interpreted in that field's default unit (mm, N, degrees...), but a few methods require an explicit Quantity — those are called out below. Import the shared unit registry with:

from springcalc.pymodels.units import ureg

length = 20 * ureg.mm
angle = 90 * ureg.degree

Material data

Material (springcalc.pymodels.material.Material) is a pydantic model that looks up a named material's mechanical properties from material/materials.csv and auto-fills any field you don't pass explicitly.

from springcalc import Material, get_available_materials

print(get_available_materials())
# ['SL', 'SM', 'DM', 'SH', 'DH', 'TDC', 'TDCrV', ...]

material = Material(material_name="SH")
print(material.young_modulus)    # 206000.0 megapascal
print(material.shear_modulus)    # 81500.0 megapascal
print(material.poisson_coef)     # 0.3 dimensionless

Adding a new material — young_modulus/shear_modulus accept a unit string, a plain number (assumed MPa), or a Quantity; elastic_limit_factor and poisson_coef are dimensionless. Once created, the material is loadable by name like any built-in one:

from springcalc import Material

custom = Material.create_material(
    material_name="CustomSteel",
    young_modulus="210000 MPa",
    shear_modulus=81000,
    elastic_limit_factor=0.5,
    poisson_coef=0.3,
    description="Custom steel for a special order",
    RMa_data=[(1.0, 1600, 1800), (2.0, 1500, 1700)],  # (diameter mm, RMa_min, RMa_max)
)

# From now on it behaves like any other material
same_material = Material(material_name="CustomSteel")

Wire characteristics

WireCharacteristics (springcalc.pymodels.wire_characteristics.WireCharacteristics) is the base class of every spring type. Given a material and a wire diameter, it looks up the wire diameter tolerance and the tensile-strength range (RMa) for that diameter.

from springcalc import Material
from springcalc.pymodels.wire_characteristics import WireCharacteristics

material = Material(material_name="SH")
wire = WireCharacteristics(material=material, wire_diameter=2.0)
print(wire.diameter_tolerance)          # 0.025
print(wire.RMa_min, wire.RMa_max)       # 1980.0 2200.0

Compression springs

CompressionSpring (springcalc.lineal.compresion.CompressionSpring, also exported as springcalc.CompressionSpring) is the main entry point for helical compression springs. It extends LinealSpring (springcalc.lineal.lineal.LinealSpring), the shared calculation engine also used by ExtensionSpring.

from springcalc import Material, CompressionSpring

material = Material(material_name="SL")
spring = CompressionSpring(material=material, wire_diameter=2.5)
spring.set_geometry(outer_diameter=30, pitch=20, free_length=100)  # mm

# Equivalent to calling separately:
#   spring.set_diameter(outer_diameter=30)
#   spring.calculate_spring_properties(pitch=20, free_length=100)

for length_mm in [30, 40, 50, 60, 70, 80, 90, 100]:
    spring.add_load_position(length=length_mm)

data = spring.get_spring_data()
print(data["spring_constant"])          # ~7.09 N / mm
print(data["wahl_factor_category"])     # 'green' -> C=11 is in a normal manufacturable range

# Graphs (base64 PNGs, ready to embed in HTML or a PDF)
load_vs_position_png = spring.get_forces_vs_position_graph()
diameter_png = spring.get_diameter_vs_position_graph()

# Fatigue analysis from the recorded positions
result = spring.create_goodman_diagram()
print(result["analysis"]["safety_factor"])

Extension springs

ExtensionSpring (springcalc.lineal.extension.ExtensionSpring, also exported as springcalc.ExtensionSpring) models helical extension springs. It extends LinealSpring directly (not CompressionSpring) and its diameter/length setters require explicit Quantity values rather than plain numbers.

from springcalc import Material, ExtensionSpring
from springcalc.pymodels.units import ureg

material = Material(material_name="SH")
spring = ExtensionSpring(material=material, wire_diameter=1.5)
spring.set_diameter(outer_diameter=15 * ureg.mm)   # note: needs a Quantity, unlike CompressionSpring
spring.calculate_spring_properties(nr_coils=10, free_length=60)

spring.calculate_positions_table([65, 70, 75, 80])  # extend beyond the free length

data = spring.get_spring_data()
print(data["spring_constant"])   # ~2.33 N / mm

result = spring.create_goodman_diagram()
print(result["analysis"]["safety_factor"])

Torsion springs

TorsionSpring (springcalc.lineal.torsion.TorsionSpring, also exported as springcalc.TorsionSpring) models helical torsion springs, tracking angular position/travel and torque instead of linear load. It extends WireCharacteristics directly and has no Goodman/fatigue integration.

from springcalc import Material, TorsionSpring
from springcalc.pymodels.units import ureg

material = Material(material_name="SH")
spring = TorsionSpring(material=material, wire_diameter=1.0)
spring.set_geometry(
    mean_diameter=10 * ureg.mm,
    nr_coils=8,
    pitch=1.2 * ureg.mm,
    free_angle=180 * ureg.degree,
    fixed_leg_radius=15 * ureg.mm,
    mobile_leg_radius=15 * ureg.mm,
)
print(spring.spring_constant)   # ~35 mm*N/rad

spring.add_position(angle_travel=30 * ureg.degree)
for position in spring.get_positions():
    print(position)

Fatigue analysis (Goodman diagram)

springcalc.lineal.goodman implements the modified-Goodman fatigue check (Shigley, ch. 6/10) for spring wire in torsion, axial, or flexural loading. CompressionSpring.create_goodman_diagram() and ExtensionSpring.create_goodman_diagram() use this internally, but it can also be used directly.

from springcalc import Material, GoodmanData, GoodmanAnalyzer

material = Material(material_name="DH")
data = GoodmanData(material=material, diameter=1.0, load_type="torsion", cycles=1e5)
analyzer = GoodmanAnalyzer(data)

sigma_max, sigma_min = 400, 100   # MPa
print(analyzer.calculate_safety_factor(sigma_max, sigma_min))
summary = analyzer.get_analysis_summary(sigma_max, sigma_min)
print(summary["strengths"]["Se_MPa"], summary["strengths"]["Sf_MPa"])

Using the standalone helper directly on a CompressionSpring instance (see the Compression springs example for how spring was built), instead of calling spring.create_goodman_diagram():

from springcalc.plots import generate_goodman_diagram
from springcalc.pymodels.units import ureg

result = generate_goodman_diagram(spring, initial_length=100 * ureg.mm, final_length=40 * ureg.mm)
print(result["analysis"]["safety_factor"])

Position tables

Every spring stores its recorded working positions in a pydantic list model under .positions, populated via each spring's add_load_position/ add_position method rather than built by hand — but they're documented here since .get_data_positions() returns their contents.

# `spring` is any CompressionSpring/ExtensionSpring/TorsionSpring instance
# with load positions already recorded via add_load_position/add_position.
for position in spring.get_data_positions():
    print(position.position, position.load, position.stress)

PDF reports

SpringPDFReport (springcalc.report.SpringPDFReport, also exported as springcalc.SpringPDFReport) renders a CompressionSpring's data, a 3D isometric view, curves, and the Goodman diagram into a printable PDF using reportlab.

from springcalc.report import SpringPDFReport

# `spring` is a CompressionSpring instance (see the Compression springs example)
report = SpringPDFReport(spring, title="Spring XYZ-123")
report.build("spring_report.pdf")

Advanced: variable-geometry springs

VariableLinealSpring and CompressionSpringGeneral (springcalc.lineal.generic_lineal / springcalc.lineal.generic_compression) model compression springs whose mean diameter and/or pitch vary along their length (e.g. conical or barrel springs), by numerically integrating along the helix instead of using the constant-geometry closed-form equations. They are not exported from the top-level springcalc package — import them from their modules directly. For a constant-diameter, constant-pitch spring they agree with the closed-form CompressionSpring results.

from springcalc import Material
from springcalc.pymodels.units import ureg
from springcalc.lineal.generic_compression import CompressionSpringGeneral

material = Material(material_name="SH")
spring = CompressionSpringGeneral(material=material, wire_diameter=2.0)
spring.set_geometry(
    func_D=lambda h: 20 * ureg.mm,
    func_p=lambda h: 6 * ureg.mm,
    free_length=60 * ureg.mm,
    type_of_end="open_ground",     # optional; this is the default
    type_conforming="cold_formed", # optional; this is the default
)

spring.calculate_theta_max()
print(spring.calculate_spring_constant())   # matches G*d^4/(8*D^3*n_active) for constant geometry
print(spring.nr_active_coils)               # 7.7 (10 total coils minus the non-deforming ground ends)

deflection, force, stiffness = spring.simulate_progressive_compression(max_deflection=20 * ureg.mm, steps=20)
print(force[-1])   # ~52.92 N

Animating progressive compression

CompressionAnimator (springcalc.lineal.animation.CompressionAnimator) renders simulate_progressive_compression's result as an animated GIF of the coils closing up under load, reusing the same helix geometry as get_3d_plot. It takes any VariableLinealSpring (e.g. CompressionSpringGeneral). Saving is done with matplotlib's PillowWriter, so no extra system dependency (like ffmpeg) is required.

from springcalc import Material
from springcalc.pymodels.units import ureg
from springcalc.lineal.generic_compression import CompressionSpringGeneral
from springcalc.lineal.animation import CompressionAnimator

material = Material(material_name="SH")
spring = CompressionSpringGeneral(material=material, wire_diameter=2.0)
spring.set_geometry(func_D=lambda h: 20 * ureg.mm, func_p=lambda h: 6 * ureg.mm, free_length=60 * ureg.mm)

animator = CompressionAnimator(spring)
animator.create_gif(max_deflection=25 * ureg.mm, output_path="compression.gif")

Tests

uv run pytest

Retraining the regression models

The included JSON coefficient files are already fitted. To regenerate them:

uv run python scripts/regresiones/factor_f/factor_f.py