Ask a run to stop
stop_runRequests a running topology optimization run to stop after its current pass by writing a stop file, then returns immediately without interrupting or waiting.
Instructions
Ask a running run to stop at the end of its current pass. Returns at once; sends no signal; waits for nothing.
The tool writes the file job.stop in the run folder. The run then ends with exit code 5. There is no post step and no result/. The history, the snapshots and the checkpoint are those of a run that goes on, so run_topopt with resume=true (no allow_changed_inputs) gives the same result as a run that was not stopped.
run_dir: the run folder. Default: the run that this server started and that still works; else the one run in the work folder (or its runs/ folder) that a live process holds the job lock of (this finds a run that the CLI started). If several runs are live, the reply lists them and writes nothing: give run_dir.
The reply has state:
stop_requested: the request is written. pid, iteration (the pass at the last status), message, options.
already_requested: a request is in the folder already (stop_request has its time); it is not written again.
postprocess: the run is in the post step or the refine step: all passes are done, nothing is written. Options: wait, or end the process yourself (resume=true then repeats the post step only).
nothing_to_stop: the run is done, stopped or failed already: nothing is written. process_alive says whether a process of this server is alive and only serves the dashboard. options has the resume route where a checkpoint is there.
gone: a lock whose process is not running, or a record that says running and has no lock: nothing is written. checkpoint and the option resume=true (it replaces the stale lock, with a fact). Also the run process of this server that ended before it took the job lock: the message has its exit and the log file.
none: no run in this folder: no job files and no live process, or the folder does not exist, or a live job lock of a job that is not a topopt run (the message names the marker, for example ratchet.json). Nothing is written.
several: several live runs: the list is in runs.
Every reply has note: a topopt build from before this change does not read job.stop, and a run of such a build ignores the request. found_by says how the run was found (run_dir, this server, the lock scan).
The run reads job.stop after the checkpoint of each pass (one file read per pass, no polling). It then saves its verdict (state stopped_by_request), writes the status stopped and the job marker job.STOPPED, and releases the job lock. A pass that is long (a big grid, a buckling row) delays the stop by up to one pass. A solve that hangs never reads the request: the reply has the pid.
With run_topopt fine_pass=true and no run_dir, the fine pass is stopped when it runs; while the first run works, that run is stopped and the fine pass does not start. From the post step of the first run until the fine pass has started, the request is written in the fine folder (state stop_requested, run_dir the fine folder): the process reads it before the fine pass starts, ends without starting it (exit code 5) and says so in the log.
Only run folders count for run_dir: a folder with status.json or run.json, as in list_runs. The folder of a ratchet job holds a job lock too, and it is not a run.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_dir | No |