Command Scripts

A command script is a list of terminal commands. Use scripts to rebuild a model from exact inputs, to apply the same edits to several projects, to run a study and check its results, or to keep a record of how a model was built.

Writing a script

Open the terminal and choose the Script tab. Type or paste commands into the editor, one per line, using the same syntax as the Console. Blank lines and lines starting with # are ignored. The terminal commands help and clear belong to the Console and are not allowed in a script.

# A 15 m high cut in two materials, both below a water table.
boundary.set points=[[0,0],[80,0],[80,20],[50,20],[30,35],[0,35]]
material.add id="clay" name="Stiff clay" properties={"unitWeight":19,"cohesion":12,"frictionAngle":24,"waterSurface":"water-table"}
material.add id="sand" name="Dense sand" properties={"unitWeight":20,"cohesion":0,"frictionAngle":36,"waterSurface":"water-table"}
material.boundary.add id="mb-1" points=[[0,14],[80,12]]
material.assign.region material="clay" at=[10,25]
material.assign.region material="sand" at=[10,5]
water.table.set points=[[0,28],[30,26],[50,18],[80,17]]

# Search the active scenario, print the result and save the project.
analysis.lem.run
script.echo text="Two-layer cut with a water table"
result.lem
project.save

# Fail the script if the lowest FOS is below 1.3.
result.assert minFos=1.3

material.assign.region picks a region by a point inside it, as a click would. In a project that uses the Soil Profile it assigns Soil Profile regions, otherwise analysis regions; target= chooses explicitly. The Geometry or Results tab does not matter, so a script behaves the same after an analysis has switched to Results. region.list lists the regions with a point inside each (see Settings, catalogs and geometry).

A material added with material.add uses the water table only when its waterSurface property names it. material.catalog.apply, which replaces whole catalogs, gives a material without waterSurface the water table.

An imported prescribed pressure grid stays on its material as pressureGrid. Its value contains interpolation: "thin-plate-spline", the boolean includeNegativePressure and source points with x/y in metres and pressure in kPa. Set waterSurface to "pressure-grid" to use it; that selection requires a grid. material.update accepts a complete pressureGrid object or null, and changing to another water surface retains the grid for later use.

Long values

An array or object value can continue onto the following lines until its brackets balance, and more arguments can follow on the line where it closes:

boundary.set points=[
  [0,0],[80,0],[80,20],
  [50,20],[30,35],[0,35]
]
fea.groundwater.define functions=[
  {"id":"rise","name":"Rise","interpolation":"linear",
   "points":[{"time":0,"value":10},{"time":5,"value":14}]}
] probes=[{"id":"p1","name":"Probe 1","point":{"x":20,"y":5}}]

Blank lines inside a value are allowed. A line that starts a new command or a # comment ends the value, so a missing ] is reported on its own line rather than swallowing the rest of the script. Text in quotes cannot run onto the next line, and a comment cannot sit inside a value. Each line can be up to 20,000 characters and a whole script up to 512 KiB, so a boundary with thousands of survey points or a long time function fits when it is split over lines. Errors give the line and column in the editor. The Console always takes one line.

Completion and guidance

While you type, the editor shows the usage of the command at the caret and how to write the argument at the caret, as the Console does. Tab completes the command at the caret in the same way as in the Console: command and argument names, listed values, ids and object keys. When there are several choices a list opens at the caret. Both work on every line of a command, including the lines an array or object value continues on, so the keys of an object split over several lines complete with their units shown.

Checking before it runs

The script is checked as you edit it: its syntax, command and argument names, argument values and the rules between a command's arguments, such as a closed polyline needing at least three points. Lines with problems are marked in the line-number gutter and listed below the editor; select a problem to jump to it. Run stays unavailable until the script has no problems.

When you run it, JSlope also checks the script against the model: the ids of the active scenario, followed line by line through the ids that earlier lines create and delete. It refuses the whole script, and nothing runs, when:

• a line names an id that will not exist when it runs, for example ids: No CAD object has id "bb".;
• a line creates an id that is already used, for example id: Id "a" is already used in the active scenario., or a material, scenario, group or vector field id that is taken;
• an earlier line already creates the same id (id: Line 4 already creates id "b".), or one line gives the same id twice;
• a line uses an id reserved for a built-in role, such as water-table;
• your session is unverified or you have not accepted the current Terms;
• an analysis selects Browser or Native without the appropriate product licence permissions. Cloud solving is free during early access, subject to capacity. The refusal is shown in the log; execution never silently changes location.

The check reports only what is certain and leaves the rest to the run. It does not check ids that commands generate when you leave id out. After a line that adds or edits domain geometry (the External Boundary, boundaries, the water table, weak layers, loads, supports and other drawn inputs), assigns materials to regions or segments, changes a material, support or Rockfall catalog (which can add or remove the vector fields derived from Material Boundaries), applies project settings or boundary conditions, or runs an LEM, Rockfall or Runout analysis, references to domain objects and Anisotropic Vector Fields in later lines are left to the run; so is anything after undo, redo, opening or importing a project, a Section Wizard batch, a parametric sweep, or a line that does not parse. Ids of other kinds, such as materials, catalog entries and scenarios, are usually still checked. After a scenario.switch it checks names against that scenario's ids and every id the script could have created, but no longer reports ids as taken. A scenario the script creates is not checked.

A command can still fail when it runs, for example if a point lies outside the External Boundary or an analysis does not converge.

Running a script

Select Run or press Ctrl+Enter (⌘Enter on macOS) in the editor. To run part of the script:

• Run from line N runs from the command at the caret, or the next command after a blank or comment line, to the end.
• Run selection runs the commands the selection touches.

The other lines are skipped but keep their line numbers, so the gutter and messages refer to the editor's lines. Problems in lines that do not run do not block the run. The log says what is running, for example Running script from line 12: 8 commands. or Running script lines 5–9: 3 commands.

A script starts only when JSlope is otherwise idle: no analysis or other task running, no drawing in progress and no editing dialog open. If something is in the way, the log says what.

• Lines run from top to bottom. The gutter highlights the running line.
• The log shows progress about once a second, and an analysis a line starts gets its own progress row, labelled with that line.
• The log lists every line except a model edit that succeeded quietly: queries with their answers, analyses with their reports, warnings, the line that failed, and edits that generated ids you did not give, with created: … listing them.
• Each model edit is its own undo step, as if you had typed the lines in the Console one at a time. The script is not a single undo step, and the history keeps the last 20 steps.
• A line that waits for a result, such as analysis.lem.run or project.save, finishes before the next line starts.
• The script stops at the first line that does not succeed. That line is marked in the gutter and the reason is logged. Lines that already ran stay applied; nothing is rolled back.

While a script runs, the model belongs to it: the editor is read-only, and model edits and undo from the GUI are refused with a message. You can still pan, zoom, inspect results, pick points into the Console, and run queries and control commands such as analysis.status or analysis.cancel mode="keep" in the Console. Refreshing the server runs list and cancelling a server run also keep working, from the Results pane or with server.runs.list and server.run.cancel; applying a server run's results waits for the script.

Stop cancels any open file prompt and asks the running line to stop, then ends the script. An analysis or Runout run stops and discards its partial results. A project file command stops only until it starts writing or replacing the project, and server.run.apply, server.run.cancel, server.runs.list and result.export cannot be interrupted: the script ends when that line finishes (see Running analyses). Lines that completed stay applied.

After a failure

When a script fails or is stopped, a bar above the editor offers Run from line N at that line; the lines before it are already applied. After Run selection it offers Run lines N–M instead, which stops at the end of the selection as the first run did. The bar stays only while the script is unchanged, so it never starts at a line that has moved. To fix the line first, edit it, put the caret on it and use Run from line N in the toolbar.

Running the whole script again instead usually stops at once: the check finds the first id= that the earlier run already created and refuses the script before anything runs, rather than failing part-way. Undo the applied lines, or run from the failed line.

Checking results in a script

result.assert stops a script when a stored LEM factor of safety is out of bounds, and script.echo labels the log:

script.echo text="Case A: drained"
analysis.lem.run
result.assert minFos=1.3
result.assert minFos=1.5 method="spencer"

result.assert needs minFos, maxFos or both. It checks the lowest FOS across methods unless method= names one; for a transient scenario it checks the lowest FOS across the computed stages unless stage= names one, whatever stage the GUI stage player shows. It fails with a message such as Assertion failed: FOS 1.25 (Spencer) of "Master Scenario" is below 1.3. See Results and read-back for the other result queries.

Saving and opening scripts

Scripts are plain-text .slope files. Export… saves the editor's script, and Import… replaces it with a script from a file. The editor keeps its text while the terminal is closed, until JSlope is reloaded.

A quick way to start a script is to build part of a model in the GUI, then use Send GUI lines to Script or Save session as .slope in the Console (see the output log), or copy the commands it shows.