Table of Contents

Workflow: Basic Machining Simulation

This workflow walks through setting up and running a machining simulation from scratch, including project configuration, option tuning, NC execution, and result inspection.

For the method of assembling one — build order, how to shape the mission, and the replay-and-read-the-messages acceptance test that says the project is finished — see Project Construction.

flowchart TD
    Equipment["Set machine tool &<br>controller brand/type"]
    Job["Set workpiece, fixture,<br>tool house, NC files,<br>controller offsets"]
    Option["Tune simulation options<br>(resolution, physics, etc.)"]
    Run["Run simulation"]
    View["View results"]

    Equipment --> Job --> Option --> Run --> View

Starting from Client Deliverables

A real project usually starts from a bundle a customer hands over: NC programs, part/blank CAD, a tool sheet, sometimes a machine model and a few words about how the part is clamped and zeroed. Before building anything, reconcile that bundle against the Project Data Checklist, then map each item to the steps below:

Client deliverable Maps to Setup page
NC programs (.nc, .anc, …) NC files + controller brand General NC Code Support
Tool sheet (diameters, corner radius, flute count, stick-out) Tool House Cutter Geometry
Part CAD + blank/stock CAD Workpiece IdealGeom + InitGeom Anchors and Roles; a single mesh exported from CAM instead: Workpiece from a Reference Mesh
Machine model + axis layout (3-axis, 3+1, 5-axis) Machine tool kinematic chain Machine Tool
“Where is program zero?” notes, work-offset list Program zero + work-offset table Program Zero Alignment
Material name Workpiece material + cutting parameters Project Data Checklist
Note

CAD geometry commonly arrives as STEP (.step / .stp). The workpiece and machine bodies are consumed as STL (or parametric primitives), so convert STEP to STL before import. The tool sheet's diameter and corner radius are authoritative; flute length, tooth count, helix, and stick-out are often missing and may have to be estimated from the spec string and confirmed with the client.

Tip

When deliverables are incomplete (no blank CAD, unknown work offsets, unverified machine model), you can still stand up a rough project: use the NC tool diameters, the named material, a placeholder stock box that encloses the tool path, and an identity work offset — then run a coarse pass (see §3.1) to catch gross overcut/collision while you wait for the missing data. Record every assumed value so it can be confirmed later.

1. Set Machine Tool and Controller

The machine tool and controller are fixed equipment that define the physical simulation environment.

Machine Tool

The machine tool (.mt file) provides the kinematic model and STL bodies. Once selected it rarely changes between simulations.

Controller

Select the controller brand and type (e.g., Fanuc, Heidenhain, Siemens). This determines how NC code is interpreted. See Heidenhain Support and General NC Code Support for details.

GUI Operation

Open or create a project in the HiNC application and configure machine tool and controller through the corresponding panels before setting up the job.

2. Set Job Components

With equipment fixed, configure the job-specific components that change between simulations.

Tip

For the full list of data to collect before building a project (and a customer-facing checklist), see Project Data Checklist.

Job Components

Component Description
Workpiece Geometry (STL or parametric), material, and coordinate frame
Fixture (optional) Fixture geometry that participates in collision detection
Tool House One or more cutting tools with geometry and flute definitions
NC Files The NC programs to simulate
Controller Offsets Tool offset tables, work offset tables, and other controller-specific presets
Tip

All file paths used in script commands are relative to the project directory unless an absolute path is given.

Script Access

The workpiece and fixture objects are available through Workpiece(API) and Fixture(API).

var workpiece = Workpiece;
var fixture = Fixture;

GUI Operation

Configure the workpiece and the fixture on the Equipment page, under the Control Tree's Mechanism group (Workpiece, Fixture), and the tools on the Tool House page (Cutter).

3. Tune Simulation Options

Simulation options control the trade-off between accuracy and speed.

3.1 Workpiece Entity Resolution

MachiningResolution_mm(API) sets the smallest cube width of the workpiece mesh.

MachiningResolution_mm = 0.125;

Valid values are powers of 2 (e.g., 4, 2, 1, 0.5, 0.25, 0.125). If you supply a non-power-of-2 value the system rounds it to the next finer power of 2 — 0.4 runs as 0.25 (Mesh Resolution).

Warning

Each halving of mesh width can increase computation time by up to 8x and the mesh's own memory by 4x or more. Start with a coarser resolution and refine only when needed. Before choosing, estimate the run's memory from the NC program and the workpiece: on a workpiece with a large, complex surface and a short program the mesh is nearly all of it and the width decides whether the run fits, while the step results a long program produces do not shrink with a coarser mesh — see Memory Planning.

Note

Going finer is what costs the 8x — and at the fine resolutions real NC machining needs, geometry removal is usually the bottleneck. Going coarser only saves time while geometry removal is the bottleneck. Once the mesh is coarse enough that geometry removal is already cheap (1–2 mm is already very coarse for NC), the fixed per-step costs dominate and raising MachiningResolution_mm further barely changes total time (this is why 1.0 mm and 2.0 mm can run at nearly the same speed). To speed up in that regime, reduce the step count via Machining Motion Resolution. See CPU Usage During Simulation.

3.2 Display Cache

DispCache_Mb = 260;

The display resolution depends on the cache size. Recommended value should not exceed 1000 Mb.

3.3 Machining Motion Resolution

Machining motion resolution determines the interval of each simulation step. Options:

Mode Command Description
Feed Per Cycle MachiningMotionResolution = FeedPerCycle; One step per spindle revolution (default)
Scaled Feed Per Cycle MachiningMotionResolution = ScaledFeedPerCycle(2); One step per (revolution × scale): scale > 1 → fewer steps (faster); scale < 1 → more steps (finer)
Feed Per Tooth MachiningMotionResolution = FeedPerTooth; One step per tooth pass (revolution ÷ flute count)
Fixed Pace MachiningMotionResolution = FixedPace(1, 15); Fixed linear (mm) and rotary (deg) resolution; cuts by sweeping between steps
Important

Total simulation time is governed by whichever is slower: geometry removal or the per-step fixed costs. Geometry-removal cost is set by mesh resolution; the per-step fixed costs (physics, thermal/wear, per-step bookkeeping) are set by the number of steps — the motion-resolution mode plus the spindle revolutions along the toolpath, independent of mesh resolution and of workpiece size. At the fine resolutions real NC machining needs, geometry removal is usually the bottleneck (finer = much slower). Only once the mesh is coarse enough that geometry removal is already cheap do the fixed per-step costs dominate — then raising MachiningResolution_mm further will not speed things up (this is why 1.0 mm and 2.0 mm can run at nearly the same speed); reduce the step count instead — e.g. ScaledFeedPerCycle(2) takes one step per 2 revolutions, halving the steps, at the cost of sparser force-curve sampling. See CPU Usage During Simulation.

Warning

Do not use scaled model dimensions as a substitute for adjusting mesh width. Scaling model dimensions causes internal algorithm thresholds (minimum cuttable amount, floating-point-to-fraction range) to become invalid, producing irregular geometry artifacts. Adjust resolution settings instead.

3.4 XML Configuration

Resolution can also be set in the .hincproj file, or changed mid-simulation from a script embedded in the program's own comments — @@ before the block's motion, inside the comment character the controller uses (Script Commands in NC Code):

T01 M06 (@@MachiningResolution_mm=0.03125;)

4. Run Simulation

There are four ways to drive the simulation, plus player controls.

4.1 PlayNcFile — Execute from a File

PlayNcFile(API) reads and executes an NC file.

PlayNcFile("NC/file1.nc");
Note

A session plays one run at a time, and a play that would start a second one is refused and plays nothing — PlayNcFile and the other plays of this section, and a RunNcFile(API) or RunNc(API) that code enumerates. It is refused while another thread's run plays on the session (Play--BusyAnotherThread), and, when it is started off the player thread — from a host's own thread or a web request — while a mission (playing, paused or between its commands) or a job such as the step-physics recompute holds the player (Play--Busy). A mission script's own plays run on the player thread, so the mission's hold does not refuse them. Dispose an enumerator of RunNcFile or RunNc that you walk by hand (foreach disposes it): one left undisposed keeps its thread registered as playing, and every other thread's play is refused until the session ends.

4.2 PlayNc — Execute from a String

PlayNc(API) executes NC code directly from a string, useful for programmatic or dynamically generated commands.

double x = 10.0;
PlayNc($"G01 X{x} Y20 F100", "Generated Command");

4.3 PlayCsvFile — Drive from CSV Data

PlayCsvFile(API) drives the simulation from a CSV file containing axis positions, spindle speed, and feed rate.

PlayCsvFile("Data/file1.csv");

Required CSV columns (default headers): MC.X, MC.Y, MC.Z, ToolId, SpindleSpeed_rpm, Feedrate_mmdmin. Optional: MC.A, MC.B, MC.C, ActualTime, StepDuration.

Headers and timestamp values may be wrapped in double quotes; the parser strips them. ActualTime accepts either HH:mm:ss.fff or an absolute yyyy-MM-dd HH:mm:ss.ffffff form (the absolute form is required when chaining with MapSeriesByCsvFile(API), which matches by TimeTag):

"ActualTime","Feedrate_mmdmin","MC.X","MC.Y","MC.Z","SpindleSpeed_rpm","ToolId"
"2026-03-16 15:57:45.559000",10000.0,-351.745,-244.799,-215.799,1270,1
"2026-03-16 15:57:45.705000",10000.0,-351.745,-244.799,-215.799,1270,1

When a real-world controller log includes extra columns (e.g., t_receive, cnc_delay_s, status) or uses alternative column names (X/Y/Z, feedrate, spindle_speed), preprocess the file to drop or rename columns before passing it to PlayCsvFile(API).

Tip

CSV files exported by WriteStepFiles(API) can be directly read back with PlayCsvFile(API).

4.4 PlayClFile — Drive from a Cutter-Location File

PlayClFile(API) replays an NX cutter-location file (CLSF / APT-source, .cls) directly as tool motion — the machine-independent CAM toolpath, before it is post-processed for a specific machine.

PlayClFile("CL/part-op10.cls");
Note

Unlike the file players above, CL playback drives a ClMillingDevice chain — the cutter location is applied straight to the tool — not the machine-tool chain from §1. Use it to verify the programmed path itself, independent of machine and post-processor. See Cutter-Location (CL) Playback for the supported record set, tool creation from TLDATA, and the chain requirement.

4.5 Player Control

Command Purpose
Pace()(API) Insert a pausable checkpoint
Pause()(API) Pause execution
Reset()(API) Reset player state. Refused, with nothing reset, from the mission script itself (Reset--Refused) and while another thread plays an NC program on the session (Reset--Busy; POST /api/Execution/reset then answers 409); an NC program another thread starts playing on the session while the reset is in flight is refused (Play--BusyReset) 
PlayNcFile("NC/file1.nc");
if (someCondition)
    Pause();
Note

Reset between two plays of the mission. Starting the mission again after a finished run does not reset it: the new run plays on top of the machined workpiece, steps and messages the last one left, and a Record Meshed Geometry entry that reads on the first play writes instead. Over the HTTP API that is POST /api/Execution/reset before every POST /api/Execution/start — see Replay Acceptance over the HTTP API.

5. View Results

5.1 Meshed Geometry

After simulation the workpiece geometry is a Meshed Geometry (cubic mesh). You can save and reload it to avoid re-computing the initial shape:

WriteMeshedGeom("Cache/file1.wct");
ExportMeshedGeomToStl("Output/file1.stl");

To reload a saved geometry for a subsequent run:

ReadMeshedGeom("Cache/init.wct");
PlayNcFile("NC/file1.nc");

5.2 Step Data Inspection

Each simulation step carries rich data (force, torque, power, thermal, wear). Access individual steps:

var step = GetMachiningStep(100);
Message($"ToolId={step.ToolId}, Force={step.MaxAbsForce_N} N");

Total step count:

var total = StepCount;
Message($"Total steps: {total}");

5.3 Export Data

Export step-level CSV:

WriteStepFiles("Output/[NcName].step.csv");

Export waveform (shot) CSV:

WriteShotFiles("Output/[NcName].shot.csv", 1);

5.4 Messages

Use messages to log and track simulation progress:

Message("Simulation complete");
AppendMessagesToFile("Output/messages.txt");

Troubleshooting

Symptom Likely Cause Fix
Very slow simulation, large pink trail behind the tool Geometry removal is the bottleneck (mesh too fine) Increase MachiningResolution_mm (coarser mesh)
Very slow simulation, but a coarser mesh doesn't help Limited by step count (per-step physics) Reduce steps via MachiningMotionResolution (e.g. ScaledFeedPerCycle(2))
Irregular bumps on geometry Scaled model dimensions instead of resolution Use resolution settings only; see warning above
Display lag DispCache_Mb too large Reduce display cache (< 1000 Mb recommended)
Empty step data Simulation not run, no tool ever mounted, or tool not engaging workpiece Check that a tool mounts — the NC messages often carry no trace of one that did not, so look for machining steps — and that the tool path intersects the workpiece

See Also