← EGRET
Documentation/User guide
Open workspace

EGRET user guide

Configure, run, and review a simulation

This guide covers the EGRET workflow from creating a case through downloading its archived results. It describes how to operate EGRET; model science and model-specific parameter choices are covered by their own reference documentation.

Start a simulation

Quick path

A standard deterministic run

  1. 1
    Name the case

    Select an account and model, then give the simulation a recognizable name.

  2. 2
    Set the inputs

    Enter values directly, load an example, or upload a parameter file or project ZIP.

  3. 3
    Review and run

    Resolve validation messages, choose a timeout, and submit the immutable run snapshot.

  4. 4
    Inspect the result

    Monitor progress, review outputs, and download the archived run package.

Preparation

Before you start

You need an EGRET account with access to at least one workspace account. Your account determines which cases, runs, evidence files, usage records, and retained artifacts you can see.

Know the intended model inputs.

EGRET validates and records the values you provide, but it does not choose scientifically appropriate assumptions for your project. Use the parameter-name links in the workspace to open the applicable model reference.

Prepare one of the following:

  • A set of input values you will enter in the browser.
  • A supported model parameter text file.
  • A project ZIP containing a parameter file and any files it references.
  • Optional source material—PDF, Word, Excel, CSV, text, or JSON—from which you want to review proposed inputs or observed comparison results.

Step 1

Create a case

  1. Open Configure simulation.
  2. Select the account that should own the case and its stored artifacts.
  3. Select the model to run.
  4. Enter a descriptive simulation name. Include a site, scenario, or revision when that will help distinguish later runs.
  5. Optionally select a starting profile or an example case. Loading either changes the editable starting values; it does not submit a run.

A case is the editable configuration. A run is a submitted snapshot of that configuration. You can reuse a case while preserving every prior run unchanged.

Step 2

Provide model inputs

Inputs are grouped into tabs and subject areas. Some fields appear, disappear, or become unavailable when another selection changes their relevance.

Enter values in the browser

Edit a field directly. The selector on the right side of a field controls its unit or input source. Where supported, you can switch among compatible display units without changing the model's canonical value.

Load a model parameter file

Choose Upload parameter file or project ZIP. A plain text parameter file populates recognized inputs. A ZIP can also carry referenced project files. Review the populated values and the upload diagnostics before running.

Use formulas and external values

For supported fields, the input-source menu offers these modes:

Formula
Calculate a numeric value from other inputs. Formula input begins with an equals sign in uploaded parameter files.
Project file
Use a file included with the uploaded project ZIP. Keep referenced paths relative to the project structure.
URL / JSON pointer
Read an externally accessible value, optionally selecting a JSON location with a pointer such as #/depth.
Review every populated value.

Uploading or extracting data does not establish that it is technically appropriate. EGRET keeps the values editable until you submit the run.

Optional evidence workflow

Use source files

Source files are separate from model parameter files. They support evidence-backed setup and observed-versus-simulated comparisons.

  1. Drop files into Source files or choose them from your device.
  2. Start extraction for the relevant file. EGRET proposes model inputs and reported results rather than silently applying them.
  3. Inspect each proposed value, unit, confidence, source location, and excerpt.
  4. Select only values you have validated, then choose Use selected values.

Accepted inputs populate the case. Accepted observed results are retained as comparison evidence and can be displayed beside simulated outputs after the run.

Step 3

Review and run

  1. Read the validation summary. Correct every item that needs attention.
  2. Confirm that conditionally enabled fields match the intended configuration.
  3. Choose a run timeout. The timeout limits model execution; it does not include time waiting in the queue.
  4. Select Save case & run simulation.

Submission records the inputs, model version, settings, evidence references, submitting user, and execution request together. Changing the case afterward does not change the submitted run.

Execution

Monitor or cancel a run

The result view reports whether the run is queued, running, succeeded, failed, or cancelled. Long-running Monte Carlo jobs also report completed samples, the current sample, elapsed time, and an estimated remaining time.

If a run remains queued, open Jobs & workers. Depending on your role, you can inspect queue activity and worker availability. Starting, stopping, draining, or resuming workers is restricted to authorized operators.

Use Cancel run when a queued or running job should stop. Cancellation can take a short time after model execution has begun.

Results

Review and download results

A successful run can provide:

  • Highlighted outputs selected for the current model.
  • The complete structured result grouped by output category.
  • Observed-versus-simulated comparisons when accepted evidence is available.
  • Saved plots created from compatible result series.
  • Monte Carlo distributions, percentiles, and sensitivity results when applicable.

Choose Download run package to obtain the archived inputs, settings, results, diagnostics, and manifest available for that run. Availability is subject to the account's artifact-retention policy.

Uncertainty analysis

Run a Monte Carlo simulation

  1. Open the unit/input-source menu for a supported numeric parameter.
  2. Select Make this an MC variable.
  3. Choose a distribution and enter its parameters. EGRET supports uniform, normal, triangular, lognormal, binomial, discrete nominal, and linked variables.
  4. Repeat for each uncertain input.
  5. Set the trial count from 10 to 10,000 and choose a random seed. Reusing the seed and the same settings makes the sampling reproducible.
  6. Resolve validation messages, then select Save case & run Monte Carlo.

EGRET records every sampled input and collects all model outputs. Larger trial counts take longer and consume more compute resources.

After the run

Reuse, compare, and retain work

Simulation library

Open the Simulation library to find your stored cases and runs. You can reopen a prior run's input snapshot as the starting point for a new case without changing the original.

Compare runs

Use Compare runs to select compatible stored runs and examine their inputs and outputs side by side.

Retention and deletion

Stored artifacts follow the account or user retention policy. Deleting a simulation permanently removes its stored files, run record, and calculated results. Download anything that must be retained before deletion or expiration.

Common issues

Troubleshooting

The run button is available, but validation reports problems

Follow the validation list to the affected fields. Check number ranges, required values, array formatting, formulas, file references, and conditional inputs.

A parameter upload did not populate the expected fields

Open the upload log, confirm that the correct model is selected, and verify the file format and parameter names. With a ZIP, confirm that the intended parameter file is the project entry point.

The run remains queued

Check Jobs & workers for active capacity, paused submissions, or a drained queue. Contact an EGRET operator if you cannot manage workers.

The run timed out or failed

Review the displayed diagnostic, confirm that referenced files or URLs are available to the worker, and retry only after correcting the cause. Increase the timeout when the configuration is valid but legitimately needs more execution time.

An archived package is no longer available

The account's retention policy may have removed stored artifacts. The interface reports retention state; expired artifacts cannot be reconstructed unless you downloaded them previously.

Related documentation

Model and API references

These references are intentionally separate from the EGRET operating guide: