Parameter Sweep

Sweep extends a single calculation into a parameterized batch calculation. On this page, you define which input parameters should vary and how each parameter should vary across a range. The software then generates combinations and executes them automatically.

The responsibility of this page is to define parameterized inputs. It does not interpret the resulting plots; result interpretation belongs to the result chapters.

Page Role and Use Cases

Before opening Sweep, the following prerequisites should usually already be satisfied:

1. Structure is stable, and layer/group names are no longer changing frequently.
2. Optics already contains at least one valid single-run configuration.
3. You have executed a normal Run once and confirmed that the baseline result is physically reasonable.

From an engineering standpoint, Sweep is mainly used for the following questions:

If the structure is still being renamed, reordered, or heavily edited, do not start with Sweep. Path references will keep invalidating and maintenance cost rises quickly.

Page Structure and Workflow

The Sweep page has two main areas:

1. The top toolbar, which creates, duplicates, reorders, and deletes sweep items.
2. The sweep table, which defines the path and numeric range of each sweep item.

Use the following working order:

1. Create the first sweep item.
2. Select the path first, then fill From / To / Step.
3. Complete one single-parameter sweep and validate the trend.
4. Add a second parameter only after the first one is correct.
5. Before running, check duplicate paths, invalid paths, and total combination count.

The purpose of this order is simple: validate the path model first, then increase calculation scale. Otherwise the same mistake is copied into multiple rows.

Toolbar Operations

The top toolbar contains Add / Insert / Duplicate / Move Up / Move Down / Delete, and all of them operate on the currently selected row.

Duplicate is the easiest way to introduce an error: if both copied rows remain enabled and still point to the same path, validation immediately fails with a duplicate-path error.

Sweep Table Fields

The core fields in the sweep table are:

One important implementation detail is that disabled rows are ignored by duplicate-path checks and ignored by range checks. This allows you to keep draft rows in the table without blocking the current run.

Parameter Path Model

Parameter uses a cascade path picker. Available paths are generated from the current model state, not entered as free text, so they change with Structure, Surroundings, and Optics.

The current picker is divided into three groups:

1. Structure
2. Surroundings
3. Optics

Structure Paths

Structure is the most common source of sweep variables. It is generated from the names of the current top-level structure elements.

For internal group layers, the stored value path is written as ['structure', groupName, 'layers', layerName, property]. If the internal layer name changes, the old path will not auto-update; it must be selected again.

Surroundings Paths

Surrounding-medium paths are split into the incidence side and the transmission side:

The incidence side does not support k. If the medium currently uses File mode, the corresponding refractive-index property is rejected immediately.

Optics Paths

The current Sweep page exposes only two optics paths:

1. optics > incidentAngle
2. optics > pRatio

The current UI does not support direct sweeping of:

• wavelengthFrom / wavelengthTo / step
• detector enable switches
• incident-spectrum source
• visible-color enable state

In implementation terms, this page intentionally restricts sweep variables to structure parameters plus two core continuous optics variables. That is the current product boundary, not a missing menu item.

Validation Logic and Common Failure Modes

A path appearing in the picker does not guarantee that it is finally valid. The system still performs property-level validation, numeric-range validation, and reference-validity checks.

Property-Level Restrictions

If the path targets refractive-index-related properties, validity also depends on the current mode of the corresponding layer or medium.

indexType restrictions for layers and internal group layers

Therefore, when a layer is switched to File, n / k / nExt / kExt become invalid even if the path structure itself exists.

Surrounding-medium mode restrictions

Surrounding media follow the same rule set:

Numeric Range Rules

Every enabled sweep item must satisfy the following baseline rules:

1. From, To, and Step are all filled.
2. From < To.
3. Step > 0.

Several common mistakes:

• From = To is invalid. If only one fixed value is needed, use a normal single calculation instead.
• Negative step is invalid. The current sweep logic always assumes forward progression.
• Extremely small step may still pass validation, but it can increase point count and runtime sharply.

Special Rules for repeatCount

repeatCount is discrete and must remain a positive integer, not a general real-valued parameter. Therefore, when sweeping group repeat count:

1. From must be a positive integer.
2. To must be a positive integer.
3. Step must be a positive integer.
4. The generated sequence must also remain a positive-integer sequence.

For example, 1 -> 5, step 0.5 increments mathematically, but it is still invalid in this context.

Typical Causes of Path Invalidation

Most Sweep failures come from model-state changes rather than the numbers themselves.

Multi-Parameter Sweep and Baseline Usage

When two or more sweep items are enabled, the system does not execute them independently. It builds combinations from each row’s value list.

For example:

1. incidentAngle: 0 -> 60, step 20 gives 4 values.
2. pRatio: 0 -> 1, step 0.5 gives 3 values.

The final run count is 4 × 3 = 12, not 4 + 3 = 7.

The key engineering question in multi-parameter sweep is whether the total combination count is acceptable. Estimate the total combinations before adding the second parameter.

Single-parameter baseline case

The safest first sweep case is:

1. Add one sweep item.
2. Choose optics > incidentAngle.
3. Set From = 0.
4. Set To = 80.
5. Set Step = 10.
6. Keep the row enabled.
7. Launch the run using the global top-toolbar Run Sweep.

This is one of the easiest sweep types to interpret and the least dependent on structure details.

Two-parameter baseline case

If you want to extend to a two-parameter sweep, the preferred pair is:

1. First row: optics > incidentAngle
2. Second row: optics > pRatio

This pair is stable because:

1. Neither path depends on layer names.
2. Both are continuous variables.
3. Neither is restricted by File refractive-index mode.

By contrast, directly sweeping a layer n / k or internal layer parameters is much more sensitive to indexType and naming changes.

Pre-Run Checklist and Next Step

Before executing Run Sweep, verify the following:

1. Every enabled sweep item has a valid path.
2. No two enabled rows use the same path.
3. Every enabled row satisfies From < To and Step > 0.
4. If the path is repeatCount, all three values are positive integers.
5. If you are sweeping refractive-index properties, the target is not currently in File mode.
6. You have estimated the total combination count and confirmed that the run size is acceptable.

After this, continue with the next chapter: Optimizer.