Drilling calculations (user guide)

mfgparams calculates parameters for twist-drill drilling, alongside milling (end milling and face milling). This page covers using it from the interactive text GUI; see Drilling API reference (developers) for the library API.

Selecting an operation in the text GUI

Launch the text GUI with:

mfgparams

(equivalently, python -m mfgparams or python -m mfgparams.console — all three reach the same interface.) A persistent menu bar stays visible at the top of the screen: Exit, Machining, Configuration, About, Help — each reachable with the arrow keys and Enter, or its underlined keyboard shortcut. Selecting Machining expands a tree in place, showing Milling and Drilling as flat leaves; selecting Drilling opens its operation screen directly, with no further tree-level expansion. It appears as a centered, bordered floating window over the menu bar and tree (which stay visible underneath, untouched): the left pane lists every drilling input at once (unit system, calculation mode, material type, material, drilling tool, drill diameter, hole depth, available power), all simultaneously visible and editable, with no separate screen per field; the right pane shows the live result, updating automatically as you fill in or change an input. Choosing Milling instead switches to the flow described in Milling calculations (user guide).

Up/Down (or j/k) always moves to the next/previous field, regardless of its type. A radio field (unit system, mode, material type, material, and tool) is always a single Label: value line — Left/Right/h/l/ Space cycle its value with wraparound and commit it immediately, with no separate confirm step. Once metal is chosen as the material type, the Material field also opens a dedicated selection window on Enter, on top of that ordinary cycling — see Selecting a metal material below. Numeric fields (drill diameter, hole depth, available power) become editable the instant you select them — start typing a digit (or ./-) and it edits the field’s buffer immediately, no separate “start editing” step; Left/Right nudges the buffer up or down by a small step: drill diameter and hole depth nudge by 1 mm under the metric unit system, or 0.1 in under the imperial unit system — a whole-inch step is too coarse for these dimensions — while available power nudges by the shared 1 display-unit step under either unit system; Backspace removes the last character. That text is only written to the field once you navigate away from it (Up/Down) — text that still doesn’t parse as a number at that point is discarded (the field keeps its last valid value) and a message appears in the status bar beneath both panes until you correct it.

Pressing Escape moves focus back to the menu bar without closing the open operation window or changing the tree’s expand/collapse state — so you can collapse the Machining tree to see more of the screen without losing your place. Pressing Escape again, from the menu bar, closes the operation and returns to the menu bar/tree, letting you start another calculation — the same operation or a different one — without leaving the text GUI. Each operation remembers its own previous answers as defaults for the rest of the session, so switching from drilling to milling and back does not lose your drilling inputs.

Selecting a metal material

Once metal is chosen as the material type, the Material field still cycles one material at a time with Left/Right/h/l/Space, exactly like any other radio field — but pressing Enter on it instead opens a centered selection window for finding a material by more than just cycling through the list. It lists every metal material in three columns — common name, EN material number (e.g. 1.0038), and shortened/DIN-style designation (e.g. S235JR) — with an independent search field for each column; a material missing a recorded number/designation shows that cell blank. Tab/Right and Shift+Tab/Left switch which column’s search field receives typed characters, without losing text already typed into the others; typing narrows the list to materials matching every non-empty search across all three columns at once. Up/Down move the highlighted row; Enter selects the highlighted material and closes the window; Escape closes it without changing the current selection. Reopening the window always starts with the material you already had selected (if any) highlighted, and every search field cleared. A materials config file can add material_number/short_notation to a [[materials]] entry to make it searchable this way too — see specs/023-material-selector-dialog/contracts/materials-config-schema-delta.md. Non-metal material types are unaffected and only ever offer the ordinary Left/Right/Space radio-cycling behavior, with no selection window.

Drilling inputs

After the unit system, calculation mode, material type, material and tool, drilling asks for two geometry values:

Prompt	Meaning
Drill diameter	Diameter of the twist drill, in mm / in.
Hole depth	Depth of the hole to be drilled, in mm / in.

Calculation modes

Right after choosing the unit system, the text GUI asks for a calculation mode: standard, power-constrained, or fixed-rpm.

standard

The unconstrained calculation used throughout the rest of this guide. Available power stays optional and only advisory: if the calculated power exceeds it, the result is shown anyway with a warning.

power-constrained

Available power becomes a required field instead of an optional one, and the result label always reads “adjusted to fit available power” instead of “recommended” — regardless of whether an adjustment actually happened. If your machine can already deliver the calculated power the numeric values are unchanged even though the label switches. Otherwise the spindle speed is reduced until the power required matches what you supplied exactly. A budget too small for any feasible spindle speed produces an “infeasible power budget” error in the right pane in place of a result — correct the available-power field in place to retry, without leaving the screen.

fixed-rpm

Adds a required “Target spindle speed (RPM)” field. The spindle speed in the result is exactly what you entered — labeled “user-specified” — and every other value is recomputed for that speed. Available power stays optional/advisory here too, so an insufficient machine still produces a result, with a warning.

Switching mode on an open Drilling screen clears any previous mode’s power/RPM answer rather than carrying it over as a stale default.

Reading the results

A drilling result looks like this (10 mm diameter, 25 mm depth, Mild Steel, Carbide, standard mode):

Spindle speed:     1989.4 RPM   (recommended)
Feed rate:         437.7 mm/min
Machining time:    0.06 min
Torque:            10.5 N·m
Power required:    2.18 kW

These five lines mean the same as they do for milling: spindle speed and feed rate describe how the drill is driven, machining time is how long the hole takes to cut, and torque/power are what the spindle needs to deliver. Drilling does not report a material removal rate — that line is specific to milling and never appears in a drilling result.

If you supply an available machine power and the calculated power exceeds it, the result is still shown, with a warning line telling you the cut is beyond what the machine can deliver.

Limits and validation

Drill diameter and hole depth are validated as part of the calculation itself: an out-of-range value produces a clear, actionable error in the right pane rather than a result, and the field stays editable in place to correct it — nothing is discarded and the session never aborts. Text that cannot be parsed as a number at all (rather than a number that is merely out of range) is caught even earlier, before it ever reaches the calculation, with its own distinct message. The bounds themselves are:

Setting	Default	Applies to
max_diameter_mm	100.0 mm	Drill diameter.
max_depth_mm	500.0 mm	Hole depth.

In addition, both values must be positive, finite, and within the bound above. NaN, +inf/-inf and non-numeric values are all rejected as INVALID_DIAMETER/INVALID_DEPTH before the bound is checked, so the CLI re-prompts for them — including the literal nan that float() happily parses as nan — rather than letting a NaN poison the calculation (fixed in issue #56).

Library callers can override these bounds via calculate()’s config_path argument (see Drilling API reference (developers)); the CLI does not expose an equivalent flag — its only configuration flag, --materials-config, overrides materials/tools, not these geometry bounds.

Assumptions

The drilling model uses standard twist-drill machining formulas as published in widely-referenced industry sources (Sandvik Coromant’s “Machining Formulas” reference and Machinery’s Handbook), including a point-engagement allowance approximated as a fraction of drill diameter to account for the drill point’s cutting geometry when computing machining time. See specs/001-metal-drilling-calc/research.md for the formulas and their sources.