Units & sign conventions

Every dimensional PileCalc request declares unitSystem: "si" or unitSystem: "us". In the app you simply pick Metric or US and every label, input, and result follows. Direct API callers must use the corresponding coherent unit bundle below; ambiguous or mixed-unit requests are rejected.

Switching units in the app

The Metric / US switch lives in the app header, next to the theme toggle. Flip it and the whole workspace re-expresses itself — field labels, the values you've entered, the summary numbers, charts, and tables all convert instantly. Your preference is remembered across sessions.

You can't create a mixed-unit model

Under the hood PileCalc keeps every value in one canonical system (SI) and converts only at the moment of display. That means the engine is never handed a mix of, say, pcf and ksf — switching units can't corrupt your model, and results are always self-consistent. It also lets the US view show the familiar geotechnical units below rather than forcing one rigid system.

What each system shows:

Quantity	Metric	US
Length / depth / diameter	m	ft
Deflection / settlement	mm	in
Force / capacity	kN	kip
Moment	kN·m	kip·ft
Strength / pressure (c, qu, bearing)	kPa	ksf
Soil unit weight (γ)	kN/m³	pcf
Subgrade modulus (k)	kN/m³	pci
Steel modulus / yield (E, Fy)	kPa	ksi
Bending stiffness (EI)	kN·m²	kip·ft²

Declared units by design

The engine performs no guesswork about dimensional values. With unitSystem: "si", use m, kN, kPa, kN/m³, kN·m, and kN·m². With unitSystem: "us", use ft, kip, ksf, kip/ft³, kip·ft, and kip·ft². Outputs remain in the same declared bundle. The API rejects a missing unit system, but dimensional consistency within the selected bundle is still the caller's responsibility.

One system, end to end (when calling the API)

Pick the declared SI or US bundle and use it for every input. For example, do not combine ksf cohesion with pcf unit weight: the coherent US API unit for weight density is kip/ft³. The app's display layer performs the familiar pcf/ksi conversions before submitting its canonical request.

Staying consistent

Inside the app the switch keeps you consistent automatically. The rule only bites when you call the engine through the API, where you must declare and use either SI (m, kN, kPa, kN·m, kN/m³, kN·m²) or the kip–footsystem (ft, kip, ksf, kip·ft, kip/ft³, kip·ft²).

Why the app's US labels look friendlier than a strict English system

A strictly self-consistent English system would express unit weight in kcf (kip/ft³) and the subgrade modulus in kcf too. The app's US view instead shows the familiar pcf for soil unit weight, pci for subgrade modulus, and ksi for steel — because it converts each quantity individually around an SI core, so the displayed units never have to agree with one another.

The water-unit-weight trap

The single most common unit error in axial and drilled-shaft analyses is the water unit weight. Effective vertical stress — which drives both side friction and end bearing — is built by subtracting pore pressure from total stress:

σ′v = σv − u = Σ(γ·Δz) − γ_w·(z − z_w)

Effective vertical stress below the water table

PileCalc has no hidden water-unit-weight default. Whenever groundwater affects an analysis,waterUnitWeight is required. Omitting it fails validation rather than silently selecting 9.81 or 62.4. A pcf value must never be sent directly in a kip–foot API request.

Set γ_w to match your units

SI API: γ_w = 9.81 kN/m³. US API: γ_w = 0.0624 kip/ft³. The app may display the latter as 62.4 pcf, but converts it before sending the request. The value must always be present when a water table is present.

Sign conventions

The engine uses a single, consistent set of conventions:

Depth is measured downward from the ground surface (or the pile head), positive into the ground. Profiles in the app are drawn with depth increasing downward, the way you read a borehole log.
Lateral deflection is positive in the direction of the applied lateral load.
Axial load is compression-positive: a positive axial force pushes down the pile. Uplift capacity is reported as a separate, positive resistance.
Bending moment and shear follow the beam-column convention of the COM624P formulation. What matters for design is the magnitude and the depth of the peak, both of which the app labels directly.

Sign conventions differ between programs

LPILE and RSPile even use opposite signs for moment and soil reaction in places. When you compare against another tool, compare magnitudes and locations, not raw signs.

Depth & geometry

Soil layers are defined by their top and bottom depths and must tile the profile without gaps or overlaps. The bottom of the last layer should reach at least the pile tip. If a pile stands partly above grade (a pier, or a scoured pile), the free length above the ground surface is entered separately and adds cantilever deflection — see the pile inputs.