# Servo-axis cycle planner

This tool compares rest-to-rest motion settings for a horizontal screw-driven inspection shuttle. It exports exact seven-phase trajectories, peak and RMS motor loading, regenerative energy, candidate rejections, and a synthetic tracking study.

The included case moves 320 mm out and back with two process dwells. The machine parameters and motor envelope are declared reference inputs. They are not measurements or a selected commercial motor.

## Run

Python 3.12 or newer is recommended.

```sh
python -m pip install -r requirements.txt
python run.py
python verify.py
python complete_validation.py
```

Open `report.html` and `completion/report.html` directly in a browser. All plots and data are local. No service, account, database or external JavaScript library is needed.

For another input file or output folder:

```sh
python run.py --inputs inputs.json --output outputs --report report.html
```

`run.py` validates inputs and exits with code 2 for invalid input or if no candidate meets all corners. If all candidates fail, the candidate CSVs are still written so the rejected limits can be inspected. It never silently relaxes the supplied acceptance limits. The shipped commissioning and regression commands validate the packaged reference configuration; they are not a certification of an arbitrary edited machine.

## Files

- `planner.py`: trajectory construction, screw-axis load model, exact polynomial duty integrals and constraint evaluation.
- `inputs.json`: travel, dwell, nominal machine, candidate grid, uncertainty corners and acceptance limits.
- `run.py`: candidate sweep, selected trajectory, plots and main calculation report.
- `outputs/selected-cycle.csv`: time, position, velocity, acceleration, jerk, torque, speed, current and energy-rate samples.
- `outputs/selected-phase-table.csv`: exact phase start states and constant-jerk durations.
- `outputs/candidate-corners.csv`: all 240 candidate/corner results, including rejected limits.
- `outputs/candidate-summary.csv`: the 48-setting decision table.
- `outputs/summary.json`: selected settings, exact integral metrics and the input snapshot.
- `test_planner.py` and `verify.py`: 20 regression tests and verification record generation.
- `complete_validation.py`: 15 synthetic/theoretical acceptance checks, including degraded tracking and overload rejection.
- `completion/tracking-35Hz.csv`, `tracking-25Hz.csv`, `tracking-8Hz.csv`: declared second-order response models.
- `verification.json`, `completion.json`: executed results and source hashes.

## What is calculated

The trajectory integrates constant jerk to obtain acceleration, velocity and position. Short moves omit phases when they cannot reach a velocity or acceleration limit. Positive and negative moves use the same signed solution. The solver accepts zero distance; otherwise travel magnitude must be between 1e-12 and 1,000 m. Velocity, acceleration and jerk limits must be finite, positive and within the documented numerical range in `planner.py`.

Motor torque includes moving-mass acceleration, Coulomb and viscous drag, screw efficiency, rotating inertia and rotating drag. `rotating_inertia_kgm2` includes the motor rotor, screw and coupling only. Translating mass is accounted for separately and must not be added again to that inertia.

Power flow determines the screw efficiency factor. Motor-driven motion divides by forward efficiency; back-driving multiplies by reverse efficiency. All efficiencies must be between zero and one. The model integrates torque squared for cycle RMS loading, finds torque extrema from derivatives, and splits energy integrals at power reversals. Copper loss uses three phases, per-phase resistance, and a torque constant expressed in N m per phase-RMS ampere.

Dwell has zero torque for the declared horizontal, unloaded hold. Electronics idle consumption and iron loss are excluded. Regeneration is the negative terminal-energy integral after the declared conversion efficiency, not the net cycle energy or a DC-bus-voltage prediction.

## Result of the included study

Of 48 settings, 35 meet all five declared corners. The shortest accepted grid setting is 0.50 m/s, 2.40 m/s² and 48 m/s³. The complete cycle takes 2.39667 s including 0.60 s of dwell. Worst-corner RMS torque is 0.26000 N m and worst peak torque is 0.55827 N m, against declared limits of 0.30 and 0.62 N m.

The synthetic tracking model at 35 Hz stays within a 0.10 mm following-error allowance. The 8 Hz case is rejected. A 160 kg, 90 N-drag counterfactual is also rejected. The reports retain those failures instead of treating them as acceptable operation.

## Scope

This is a completed numerical design study and reusable planning tool. It is not drive firmware and does not issue machine commands. It covers symmetric rest-to-rest moves for one horizontal axis. It does not model vertical holding loads, arbitrary moving endpoints, backlash, compliance, collision avoidance, emergency stopping, a speed-dependent motor torque envelope, actual winding temperature, screw critical speed, bearing life, or bus capacitance.

The physical commissioning counterpart is an explicitly declared second-order tracking ODE plus quantization and parameter-corner runs. It is not measured machine accuracy or hardware qualification. Equations, independent checks and manufacturer references are in the reports.