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.

Number of downloads:

Want to help? Contact me at eacarretero@gmail.com

Visit the library on my github https://github.com/ErnestoAvedillo/springcalc and clone the 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)
└── inverse_calc/       Inverse design: find spring geometry from a target rate or curve

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 = 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
• Inverse design — CompressionSpringInverseDesigner, ConicalCompressionSpringInverseDesigner, ConicalCurveCompressionSpringInverseDesigner, GeneralCompressionSpringInverseDesigner

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"])          # ~3.60 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)    # pitch defaults to the wire diameter -> free_length = 10 * 1.5 = 15 mm

spring.calculate_positions_table([20, 25, 30, 35])  # extend beyond the 15 mm 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, wire_diameter=1.0, load_type="torsion", number_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. Unlike CompressionSpring, this class has no active-coil correction (no .calculate_active_coils()/.nr_active_coils): .nr_coils is used directly wherever CompressionSpring would use its (always smaller) active-coil count, so even for a constant-diameter, constant-pitch spring its results (e.g. .calculate_spring_constant()) don't numerically match CompressionSpring's for the same nr_coils — type_of_end is accepted (and stored) but doesn't otherwise affect the calculation here.

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(
    f_mean_diameter=lambda h: 20 * ureg.mm,
    f_pitch=lambda h: 6 * ureg.mm,
    free_length=60 * ureg.mm,
    type_of_end="open_ground",     # optional; this is the default
)

spring.calculate_theta_max()
print(spring.calculate_spring_constant())   # matches G*d^4/(8*D^3*n) for constant geometry (n = nr_coils, 10 here)

deflection, force, stiffness = spring.simulate_progressive_compression(max_deflection=20 * ureg.mm, steps=20)
print(force[-1])   # ~40.75 N (still in the linear regime at 20mm out of 60mm free length)

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(f_mean_diameter=lambda h: 20 * ureg.mm, f_pitch=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")

Inverse design

springcalc.inverse_calc (not exported from the top-level springcalc package — import from its modules directly) works backwards from a target spring rate or a target force-displacement curve to a buildable geometry, instead of computing properties from geometry you already chose. All four designers search the standard wire diameter series (get_standard_wire_diameters()), score candidates against a target fatigue safety factor (via GoodmanAnalyzer), and rebuild/verify the winning design with the library's normal spring classes before returning it — so the returned .spring behaves exactly like a spring you built by hand.

Cylindrical spring from two (or more) rate points

CompressionSpringInverseDesigner (springcalc.inverse_calc.lineal_comp_inv) finds the wire diameter and mean diameter of a standard (constant-diameter, constant-pitch) CompressionSpring that reproduces a target rate while landing the safety factor as close as possible to a target value. The number of coils is always solved so the rate matches exactly; for each standard wire diameter, the mean diameter that hits the safety-factor target is found by 1-D root finding.

from springcalc.inverse_calc.lineal_comp_inv import CompressionSpringInverseDesigner, Requirements
from springcalc.pymodels.material import Material

material = Material(material_name="SL")
requirements = Requirements(
    material=material, safety_factor=1.5,
    length1=60, force1=200,   # more compressed, higher-force point
    length2=90, force2=50,    # less compressed, lower-force point
)
result = CompressionSpringInverseDesigner(requirements).design()

print(result.wire_diameter, result.mean_diameter, result.nr_coils)
print(result.safety_factor, result.safety_factor_error)

Conical (tapered) spring from two (or more) rate points

ConicalCompressionSpringInverseDesigner (springcalc.inverse_calc.conical_comp_inv) is the same idea, but for a linearly-tapered (diameter and pitch) conical spring built on CompressionSpringGeneral. The rate and safety-factor equations alone leave the taper shape (tau_D = D_end/D_start, tau_p = p_end/p_start) free, so the extra degree of freedom is resolved by minimizing solid length — i.e. preferring the most compact (most telescoping) taper, the usual reason to choose a conical spring at all. For each standard wire diameter, the taper shape is searched on a grid and locally polished (Nelder-Mead).

from springcalc.inverse_calc.conical_comp_inv import ConicalCompressionSpringInverseDesigner
from springcalc.inverse_calc.lineal_comp_inv import Requirements
from springcalc.pymodels.material import Material

material = Material(material_name="SL")
requirements = Requirements(material=material, safety_factor=1.2,
                            length1=60, force1=200, length2=90, force2=50)
result = ConicalCompressionSpringInverseDesigner(requirements).design()

print(result.diameter_start, result.diameter_end)
print(result.pitch_start, result.pitch_end)
print(result.solid_length)

Conical (tapered) spring fit to a full force-displacement curve

ConicalCurveCompressionSpringInverseDesigner (springcalc.inverse_calc.conical_curve_comp_inv) fits a conical spring's wire diameter, free length, and diameter/pitch taper to an entire target force-vs-displacement curve (rather than just two points), so it can capture progressive stiffening from coil-to-coil contact. There's no closed form for this, so it's a regression: scipy.optimize.differential_evolution searches the 6-parameter space (wire diameter, free length, D_start, D_end, p_start, p_end), minimizing curve RMSE plus a soft safety-factor term plus a geometry penalty, using a fast closed-form contact simulation; the winning wire diameter is then snapped to the standard series and the rest locally re-fit before the final design is rebuilt with the real, general CompressionSpringGeneral machinery.

from springcalc.inverse_calc.conical_curve_comp_inv import (
    CompressionCurveRequirements, ConicalCurveCompressionSpringInverseDesigner,
)
from springcalc.pymodels.material import Material

material = Material(material_name="SL")
requirements = CompressionCurveRequirements(
    material=material, safety_factor=1.3, csv_path="target_curve.csv",  # displacement,load columns (mm, N)
)
result = ConicalCurveCompressionSpringInverseDesigner(requirements, seed=0).design()

print(result.curve_rmse, result.curve_rmse_relative)
print(result.diameter_start, result.diameter_end, result.pitch_start, result.pitch_end)

General (arbitrary-profile) spring fit to a full force-displacement curve

GeneralCompressionSpringInverseDesigner (springcalc.inverse_calc.general_comp_inv) is the same curve-fitting idea as ConicalCurveCompressionSpringInverseDesigner, but for a mean-diameter and pitch profile that isn't restricted to a straight taper: D(h) and p(h) are each a monotone cubic (PCHIP) spline through num_control_points free values, able to represent a barrel/hourglass shape or a non-monotonically varying pitch, not just two tapered ends. A spline profile has no closed-form winding-angle mapping, so unlike the conical curve designer, every candidate the search evaluates is simulated with the library's real, general (root-solve-based) machinery — expect this search to take minutes to hours rather than seconds, and prefer ConicalCurveCompressionSpringInverseDesigner whenever a simple taper already fits the target curve.

from springcalc.inverse_calc.conical_curve_comp_inv import CompressionCurveRequirements
from springcalc.inverse_calc.general_comp_inv import GeneralCompressionSpringInverseDesigner
from springcalc.pymodels.material import Material

material = Material(material_name="SL")
requirements = CompressionCurveRequirements(
    material=material, safety_factor=1.3, csv_path="target_curve.csv",  # displacement,load columns (mm, N)
)
result = GeneralCompressionSpringInverseDesigner(requirements, seed=0).design()

print(result.curve_rmse, result.curve_rmse_relative)
print(result.diameter_control_points, result.pitch_control_points)
print(result.diameter_at(result.free_length / 2))

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