Antoine/Polisher-Control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: scaffold polisher-control foundation

Browse Source
This commit is contained in:
Nick Hermes
2026-05-26 16:23:04 +00:00
commit fa9c43fae8
52 changed files with 2224 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
shared/schemas/examples/controller-job.example.json Normal file
View File

@@ -0,0 +1,32 @@
{
"schema_version": "controller-job.v1",
"controller_job_id": "cjob-2026-07-001",
"job_id": "job-2026-07-001",
"machine_id": "fullum-alpha",
"machine_capabilities_ref": "machine-capabilities-fullum-alpha-v1",
"controller_version": "polisher-control/0.1.0",
"translated_at": "2026-07-15T10:15:00Z",
"translated_by": "polisher-post/0.1.0",
"translation_notes": "All setpoints within machine limits. No clipping required.",
"segments": [
{
"segment_id": "seg-01",
"sequence_index": 1,
"source_pass_id": "pass-01",
"duration_s": 1200,
"commanded_force_n": 45.0,
"commanded_table_rpm": 4.0,
"commanded_spindle_rpm": 40.0,
"commanded_cam_amplitude_deg": 31.3,
"commanded_cam_offset_deg": 0.0,
"force_modulation": {
"harmonic": 2,
"amplitude_n": 5.0,
"phase_deg": 37.2
},
"dither_profile": "none",
"notes": "Direct translation — no segmentation needed for 1200s duration."
}
],
"translation_losses": []
}

71
shared/schemas/examples/job.example.json Normal file
View File

@@ -0,0 +1,71 @@
{
"schema_version": "job.v1",
"job_id": "job-2026-07-001",
"mirror_id": "gigabit-m1",
"machine_family": "swing-arm",
"source_map_id": "ifg-2026-07-14-pre",
"target_id": "target-m1-final-figure",
"created_at": "2026-07-15T09:30:00Z",
"created_by": "antoine",
"planner_version": "polisher-sim/0.6.0",
"calibration_state_ref": "cal-2026-06-fullum-alpha",
"strategy_summary": {
"intent": "Reduce dominant astigmatism using m=2 force modulation on 280mm tool",
"confidence": 0.72,
"notes": "Single-pass conservative correction. Dither disabled for baseline comparison."
},
"passes": [
{
"pass_id": "pass-01",
"sequence_index": 1,
"objective": "Astigmatism reduction via force modulation",
"preset_name": "figuring_standard",
"duration_s": 1200,
"force_n": 45.0,
"table_rpm": 4.0,
"spindle_rpm": 40.0,
"motion_family": "swing-arm-rosette",
"motion_params": {
"cam_amplitude_deg": 31.3,
"cam_offset_deg": 0.0,
"osc_hz": 0.25
},
"dither_profile": "none",
"force_modulation": {
"harmonic": 2,
"amplitude_n": 5.0,
"phase_deg": 37.2
},
"notes": "Phase derived from Zernike fit of pre-polish interferogram."
}
],
"predicted_outcome": {
"removal_rms_nm": 18.5,
"removal_pv_nm": 62.0,
"residual_zernikes": {
"Z4": -2.1,
"Z5": 12.3,
"Z6": -8.7,
"Z7": 15.1,
"Z8": -3.2,
"Z9": 4.5,
"Z10": -2.8
}
},
"uncertainty": {
"removal_rms_nm_range": [14.0, 24.0],
"notes": "Uncertainty dominated by Preston coefficient calibration spread."
},
"attachments": [
{
"filename": "predicted_removal.csv",
"role": "predicted_removal_map",
"description": "2D removal map in nm, 256x256 grid"
},
{
"filename": "pre_surface.csv",
"role": "input_surface_map",
"description": "Pre-polish surface map used as planning input"
}
]
}

51
shared/schemas/examples/machine-capabilities.example.json Normal file
View File

@@ -0,0 +1,51 @@
{
"schema_version": "machine-capabilities.v1",
"machine_id": "fullum-alpha",
"machine_family": "swing-arm",
"machine_name": "Fullum Swing-Arm Polisher",
"controller_version": "polisher-control/0.1.0",
"last_verified": "2026-06-01T00:00:00Z",
"supported_motion_families": ["swing-arm-rosette"],
"force_range_n": [5, 200],
"table_rpm_range": [0.5, 10.0],
"spindle_rpm_range": [10, 120],
"cam_amplitude_range_deg": [1.0, 31.3],
"cam_offset_range_deg": [-30.0, 30.0],
"force_modulation": {
"supported": true,
"max_harmonics": 3,
"max_amplitude_n": 24.0,
"notes": "m=2 astigmatism and m=3 trefoil are proven channels. m=1 coma is unreliable (score 0.09)."
},
"supported_dither_profiles": ["none", "default"],
"segment_duration_limits": {
"min_s": 30,
"max_s": 7200
},
"pause_resume_support": true,
"telemetry_channels": [
{ "name": "table_rpm", "unit": "RPM", "sample_rate_hz": 100 },
{ "name": "spindle_rpm", "unit": "RPM", "sample_rate_hz": 100 },
{ "name": "force_n", "unit": "N", "sample_rate_hz": 100 },
{ "name": "arm_angle_deg", "unit": "degrees", "sample_rate_hz": 100 },
{ "name": "table_angle_deg", "unit": "degrees", "sample_rate_hz": 100 },
{ "name": "timestamp_ms", "unit": "ms", "sample_rate_hz": 100 }
],
"safety_limits": {
"max_force_n": 200,
"max_table_rpm": 10.0,
"max_spindle_rpm": 120,
"notes": "Force hard-limited by load cell interlock. RPM limits are VFD/servo configured."
},
"known_constraints": [
"Cam amplitude is not servo-programmable — must be set mechanically before run.",
"Force modulation bandwidth limited to ~5 Hz by actuator response.",
"Table encoder is absolute but may have 1-2 count jitter.",
"Serial interface to Teensy limits command update rate to ~50 Hz effective."
],
"unknowns": [
"Exact force modulation phase accuracy at m=3 harmonic — not yet validated on hardware.",
"Thermal drift effect on force sensor over runs longer than 1 hour.",
"Arm pivot play magnitude under varying force loads."
]
}

43
shared/schemas/examples/manifest.example.json Normal file
View File

@@ -0,0 +1,43 @@
{
"schema_version": "manifest.v1",
"manifest_id": "manifest-job-2026-07-001",
"bundle_type": "job",
"source_id": "job-2026-07-001",
"created_at": "2026-07-15T09:31:00Z",
"created_by": "polisher-sim/0.6.0",
"entries": [
{
"filename": "job.json",
"role": "primary",
"hash_sha256": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"size_bytes": 2007,
"content_type": "application/json",
"description": "Frozen planning job package."
},
{
"filename": "predicted_removal.csv",
"role": "attachment",
"hash_sha256": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
"size_bytes": 524288,
"content_type": "text/csv",
"description": "Predicted removal map, 256x256 grid, nm."
},
{
"filename": "pre_surface.csv",
"role": "attachment",
"hash_sha256": "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"size_bytes": 524288,
"content_type": "text/csv",
"description": "Pre-polish surface map used as planning input."
},
{
"filename": "manifest.json",
"role": "manifest",
"hash_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
"size_bytes": 0,
"content_type": "application/json",
"description": "This manifest (self-reference, hash zeroed by convention)."
}
],
"notes": "July proving scenario — single-pass astigmatism correction job bundle."
}

64
shared/schemas/examples/run-log.example.json Normal file
View File

@@ -0,0 +1,64 @@
{
"schema_version": "run-log.v1",
"run_id": "run-2026-07-001",
"job_id": "job-2026-07-001",
"controller_job_id": "cjob-2026-07-001",
"controller_version": "polisher-control/0.1.0",
"machine_id": "fullum-alpha",
"started_at": "2026-07-17T14:00:00Z",
"ended_at": "2026-07-17T14:20:35Z",
"result_state": "completed",
"segments": [
{
"segment_id": "seg-01",
"source_pass_id": "pass-01",
"commanded_duration_s": 1200,
"actual_duration_s": 1203.5,
"result_state": "completed",
"commanded": {
"force_n": 45.0,
"table_rpm": 4.0,
"spindle_rpm": 40.0,
"cam_amplitude_deg": 31.3,
"cam_offset_deg": 0.0
},
"actual": {
"force_n_mean": 44.7,
"force_n_min": 41.2,
"force_n_max": 49.8,
"table_rpm_mean": 3.98,
"spindle_rpm_mean": 39.9
},
"pause_windows": [],
"anomaly_flags": [],
"notes": "Clean run. Minor force excursion at arm reversal points."
}
],
"commanded_summary": {
"force_n": 45.0,
"table_rpm": 4.0,
"spindle_rpm": 40.0
},
"actual_summary": {
"force_n_mean": 44.7,
"force_n_min": 41.2,
"force_n_max": 49.8,
"table_rpm_mean": 3.98,
"spindle_rpm_mean": 39.9
},
"alarms": [],
"events": [
{
"timestamp": "2026-07-17T14:00:00Z",
"type": "run_started",
"detail": "Operator acknowledged start."
},
{
"timestamp": "2026-07-17T14:20:35Z",
"type": "run_completed",
"detail": "All segments completed normally."
}
],
"telemetry_ref": "telemetry-run-2026-07-001.csv",
"operator_notes": "Smooth run. No intervention needed."
}