Parameter Set Generator API Reference¶

An overview of commands for Parameter generator for projects.

Info

This API is included in the ecu.test Interface Python Library ecutest-interface.

ParamGenerator¶

class ParamGenerator¶

Base class for iterator-based user-defined parameter set generators.

Derive from this class when the required package runs can be prepared and yielded in sequence. Implement GenerationIterator() and yield one CycleData object for each package run. Use PreGeneration() to read input files or prepare data, and use PostGeneration() for cleanup. The simple text-file implementation in examples/ParametersetGeneratorExample.py follows this workflow.

Use CallbackParamGenerator instead when the next parameter set depends on package return values from a previous run.

Some fields and methods must be overridden (mandatory), others may be overridden (optional). There are also methods that are only to be called by the user implementation and should not be overridden (those without a note).

DESCRIPTION : str = ''¶: A short description of the parameter generator.

Info

Setting this field is optional

ID : str = ''¶: A universally unique identifier to make the parameter generator unique. The ID should be generated using a UUID generator to be unique.

Info

Setting this field is mandatory

NAME : str = ''¶: The display name of the parameter generator.

Info

Setting this field is mandatory

SERIALIZE : dict[str, tuple[str, str] | tuple[str, str, object]] = {}¶

Declaration of parameter-set generator instance variables that are exported to and imported from XML when a project is saved or loaded. Add one dictionary item for each persisted instance variable. Example:

SERIALIZE = {
    'foo': ('FOO-VAR', 'integer', 23),
    'bar': ('BAR', 'string'),
    'params': ('PARAMETERS', 'list'),
}

The declaration key must match the corresponding instance-variable name. For example, an attribute named self.foo requires the key 'foo'. Each value is a tuple with at least two elements:

<variable name>: (<variable alias>, <type alias>, [default value])

Syntax and meaning of the tuple’s elements are:

<variable alias> declares the XML element name used to represent the variable.
<type alias> specifies the Python variable type. The following aliases are supported:
- boolean: bool
- integer: int
- long: int
- float: float
- string: str
- unicode: str
- list: list
- dict: dict

Important: Keys of serialized dictionaries must be strings. Values in lists and dictionaries, including nested lists and dictionaries, must be bool, int, float, str, list, or dict. long and unicode remain available only for compatibility and should not be used in new code.

<default value> is an optional element. It specifies the variable’s default value. If the variable’s value equals its default value during export the variable is not exported at all. Conversely, the variable receives its default value during import if the XML data does not provide a value for the variable.

Info

Setting this field is optional

api = None¶: Access to the internal ecu.test API. The API will be assigned at runtime, in order to be independent from ecu.test for testing purposes.

See also

Internal APIs

projectPath : str | None = None¶: Absolute path to the project file containing the generator. In case of direct execution, this is the source project. In case of static generation it is the destination project.

classmethod GetDescription()¶

Returns the description of the parameter generator. The description can be specified by setting the class variable DESCRIPTION.

Returns:: Description text of the parameter generator.
Return type:: str

classmethod GetId()¶

Returns the universally unique identifier of the parameter generator. The identifier should be specified by setting the class variable ID.

Returns:: Unique identifier of the parameter generator.
Return type:: str

classmethod GetName()¶

Returns the name of the parameter generator. The name should be specified by setting the class variable NAME.

Returns:: Display name of the parameter generator.
Return type:: str

Check()¶

Validate the generator configuration before generation.

Return user-visible error messages, or an empty list when the configuration is valid.

Returns:: List of validation error messages.
Return type:: list[str]

Info

Overriding this method is optional.

CreateCycleData(paramSet=None, constSet=None, name=None)¶

Create a CycleData object for one generated package run.

The resulting object bundles input-variable values, optional constants, a report display name, recordings, mapping items, and additional report attributes. Prefer this helper to directly creating CycleData, because ecu.test can replace it with a runtime-specific implementation.

Parameters:

paramSet : dict | None¶: Initial values for package input variables.
constSet : dict | None¶: Initial constants set before the package run.
name : str | None¶: Optional display name for this cycle in the report.

Returns:

Cycle object containing one generated package-run configuration.

Return type:

CycleData

DryGenerationEnabled()¶

Return whether the generator runs in dry generation mode.

In this mode, ecu.test creates static parameter records instead of executing package runs. Runtime constants and package return values are unavailable.

Returns:: True if dry generation mode is active, otherwise False.
Return type:: bool

abstractmethod GenerationIterator()¶

Implement this method to generate parameter sets. Each generated package run must be represented by one CycleData object, which can be created with CreateCycleData().

This method must be a Python generator function and must use yield to provide each CycleData object. Do not yield a list or another container: ecu.test validates every yielded value and accepts only one CycleData instance at a time.

During normal execution, the iterator is resumed after ecu.test has executed the yielded cycle. Code after yield can therefore call GetLastReturnSet() when the next cycle depends on return variables from the preceding package run. In dry generation mode, ecu.test creates static parameter records instead and this helper returns None.

Example:

def GenerationIterator(self):
    for line in file:
        yield self.CreateCycleData({'lineData': line})

Info

Overriding this method is mandatory

GetDialog()¶

Return a configuration dialog for this parameter-set generator.

The dialog should update this instance’s settings, normally the attributes declared in SERIALIZE. Return None when no configuration UI is required.

Returns:: Configuration dialog instance, or None if no dialog is required.
Return type:: wx.Dialog | None

Info

Overriding this method is optional.

GetLastReturnSet()¶

Return the return-variable dictionary from the most recently executed package run.

Call this method only from GenerationIterator(), after the iterator has yielded at least one cycle and has been resumed. The dictionary uses package return-variable names as keys. It is unavailable before the first completed package run and during dry generation; in both cases, this method returns None.

Returns:: Return-variable dictionary of the latest executed cycle, or None if unavailable.
Return type:: dict | None

GetParameterText()¶

Return a short summary of the current settings for the properties column.

Returns:: One-line summary text of the current generator settings.
Return type:: str

Info

Overriding this method is optional.

GetReportData()¶

Return custom information for the generator test step in the report.

Return ReportData to populate its value and comment columns. Return None to use the default report content.

Returns:: Custom report data, or None to keep the default report output.
Return type:: ReportData | None

Info

Overriding this method is optional.

GetTargetItemCount()¶

Return the expected number of generated package cycles for progress reporting.

ecu.test can call this method repeatedly while generation is running, so the value is an estimate and may be calculated dynamically.

Returns:: Expected number of generated package cycles.
Return type:: int

GetUsedMappingItems()¶

Return every mapping item used by generated analysis-package parameter sets.

ecu.test registers these mapping items for the stimulation package before generation. Define them here directly or load them from another source, but return the complete set of items that can later be supplied through CycleData.AddMappingItem().

Info

Overriding this method is optional and only necessary for parameter set generators used with analysis packages and overwriting mapping items.

Caution

This method is called before every other hook, including PreGeneration(). If mapping data is normally read during preparation, load it here as well or move the loading to a reusable helper called from this method.

Returns:: Complete list of mapping items that may be used during generation.
Return type:: list[MappingItem]

IsValidForAnalysisPackages()¶

Return whether this parameter-set generator supports analysis packages.

Return False when the implementation is intrinsically incompatible with analysis packages, so the UI can reject the configuration before execution. Returning True permits the use; it does not make an otherwise invalid runtime implementation valid.

Returns:: True if this generator supports analysis packages, otherwise False.
Return type:: bool

Info

Overriding this method is optional.

OnInit(packageInfo)¶

Process read-only information about the associated package.

ecu.test calls this method before PreGeneration() and GetDialog(). Use packageInfo to discover package input and return-variable names, types, and descriptions before constructing generated cycles or configuration UI.

Parameters:

packageInfo : PackageInfo¶: Read-only context for the associated package.

Info

Overriding this method is optional

PostGeneration()¶

Clean up after generation.

This method runs after normal generation and after exceptions from generation, including PreGeneration(). It is not guaranteed to run after an external user abort or an abort-on-error execution setting.

Info

Overriding this method is optional.

PreGeneration()¶

Prepare generation.

ecu.test calls this method before the specialized generation method. Use it to validate settings, read input files, create expensive resources, or prepare candidate data.

Info

Overriding this method is optional.

AbortError¶

class AbortError¶

Raised when ecu.test aborts a callback parameter generator execution.

ecu.test raises this exception while a Generate() implementation calls its testRunFunction. Catch it only to release resources, then re-raise it so that the package execution remains aborted.

CallbackParamGenerator¶

class CallbackParamGenerator¶

Base class for parameter generators that react to package return values.

Derive from this class instead of ParamGenerator when the next parameter set depends on the result of a previous package run or when the generator must decide explicitly when to execute a batch of cycles. Implement Generate(), create CycleData objects with CreateCycleData(), and pass one or more cycles to the supplied testRunFunction. That function executes the associated package synchronously from the generator’s perspective and returns one return-variable dictionary for every submitted cycle, in submission order.

Typical workflow:

Prepare initial candidates in PreGeneration().
In Generate(), call testRunFunction(cycleData).
Use the returned dictionaries, or GetLastReturnSets(), to calculate the next cycles.
Stop when the generator-specific completion criterion is met.

Use this model for feedback loops and optimizers. For independent, sequential cycles, use ParamGenerator instead. The advanced optimizer examples demonstrate this execution model.

DESCRIPTION : str = ''¶: A short description of the parameter generator.

Info

Setting this field is optional

ID : str = ''¶: A universally unique identifier to make the parameter generator unique. The ID should be generated using a UUID generator to be unique.

Info

Setting this field is mandatory

NAME : str = ''¶: The display name of the parameter generator.

Info

Setting this field is mandatory

SERIALIZE : dict[str, tuple[str, str] | tuple[str, str, object]] = {}¶

SERIALIZE = {
    'foo': ('FOO-VAR', 'integer', 23),
    'bar': ('BAR', 'string'),
    'params': ('PARAMETERS', 'list'),
}

The declaration key must match the corresponding instance-variable name. For example, an attribute named self.foo requires the key 'foo'. Each value is a tuple with at least two elements:

<variable name>: (<variable alias>, <type alias>, [default value])

Syntax and meaning of the tuple’s elements are:

<variable alias> declares the XML element name used to represent the variable.
<type alias> specifies the Python variable type. The following aliases are supported:
- boolean: bool
- integer: int
- long: int
- float: float
- string: str
- unicode: str
- list: list
- dict: dict

<default value> is an optional element. It specifies the variable’s default value. If the variable’s value equals its default value during export the variable is not exported at all. Conversely, the variable receives its default value during import if the XML data does not provide a value for the variable.

Info

Setting this field is optional

api = None¶: Access to the internal ecu.test API. The API will be assigned at runtime, in order to be independent from ecu.test for testing purposes.

See also

Internal APIs

projectPath : str | None = None¶: Absolute path to the project file containing the generator. In case of direct execution, this is the source project. In case of static generation it is the destination project.

classmethod GetDescription()¶

Returns the description of the parameter generator. The description can be specified by setting the class variable DESCRIPTION.

Returns:: Description text of the parameter generator.
Return type:: str

classmethod GetId()¶

Returns the universally unique identifier of the parameter generator. The identifier should be specified by setting the class variable ID.

Returns:: Unique identifier of the parameter generator.
Return type:: str

classmethod GetName()¶

Returns the name of the parameter generator. The name should be specified by setting the class variable NAME.

Returns:: Display name of the parameter generator.
Return type:: str

Check()¶

Validate the generator configuration before generation.

Return user-visible error messages, or an empty list when the configuration is valid.

Returns:: List of validation error messages.
Return type:: list[str]

Info

Overriding this method is optional.

CreateCycleData(paramSet=None, constSet=None, name=None)¶

Create a CycleData object for one generated package run.

Parameters:

paramSet : dict | None¶: Initial values for package input variables.
constSet : dict | None¶: Initial constants set before the package run.
name : str | None¶: Optional display name for this cycle in the report.

Returns:

Cycle object containing one generated package-run configuration.

Return type:

CycleData

DryGenerationEnabled()¶

Return whether the generator runs in dry generation mode.

In this mode, ecu.test creates static parameter records instead of executing package runs. Runtime constants and package return values are unavailable.

Returns:: True if dry generation mode is active, otherwise False.
Return type:: bool

abstractmethod Generate(testRunFunction)¶

Implement this method to generate and evaluate parameter sets. Each package run must be an instance of CycleData, created with CreateCycleData().

Start package runs by calling testRunFunction. The callback accepts either one cycle or a list of cycles, allowing an implementation to evaluate candidates individually or in batches. It returns one return-variable dictionary for every submitted cycle, in the same order. In dry generation mode, no package runs occur and algorithms that require return values must handle the absent results accordingly.

Parameters:

testRunFunction¶: Starts an ecu.test package run for one CycleData instance or a list of instances and returns the corresponding return-variable dictionaries. If ecu.test aborts execution, it raises AbortError. Catch this exception only to release resources, then re-raise it so the package execution remains aborted.

Info

Overriding this method is mandatory

GetDialog()¶

Return a configuration dialog for this parameter-set generator.

The dialog should update this instance’s settings, normally the attributes declared in SERIALIZE. Return None when no configuration UI is required.

Returns:: Configuration dialog instance, or None if no dialog is required.
Return type:: wx.Dialog | None

Info

Overriding this method is optional.

GetLastReturnSets()¶

Return the return-variable dictionaries from the most recent testRunFunction call.

Call this method only from Generate(), after at least one package run has completed in normal execution. It returns an empty list before the first callback execution and in dry generation mode, because no package return values are available there.

Returns:: Return-variable dictionaries from the latest callback execution.
Return type:: list[dict]

GetParameterText()¶

Return a short summary of the current settings for the properties column.

Returns:: One-line summary text of the current generator settings.
Return type:: str

Info

Overriding this method is optional.

GetReportData()¶

Return custom information for the generator test step in the report.

Return ReportData to populate its value and comment columns. Return None to use the default report content.

Returns:: Custom report data, or None to keep the default report output.
Return type:: ReportData | None

Info

Overriding this method is optional.

GetTargetItemCount()¶

Return the expected number of generated package cycles for progress reporting.

ecu.test can call this method repeatedly while generation is running, so the value is an estimate and may be calculated dynamically.

Returns:: Expected number of generated package cycles.
Return type:: int

GetUsedMappingItems()¶

Return every mapping item used by generated analysis-package parameter sets.

Info

Overriding this method is optional and only necessary for parameter set generators used with analysis packages and overwriting mapping items.

Caution

Returns:: Complete list of mapping items that may be used during generation.
Return type:: list[MappingItem]

IsValidForAnalysisPackages()¶

Return whether this parameter-set generator supports analysis packages.

Returns:: True if this generator supports analysis packages, otherwise False.
Return type:: bool

Info

Overriding this method is optional.

OnInit(packageInfo)¶

Process read-only information about the associated package.

Parameters:

packageInfo : PackageInfo¶: Read-only context for the associated package.

Info

Overriding this method is optional

PostGeneration()¶

Clean up after generation.

Info

Overriding this method is optional.

PreGeneration()¶

Prepare generation.

ecu.test calls this method before the specialized generation method. Use it to validate settings, read input files, create expensive resources, or prepare candidate data.

Info

Overriding this method is optional.

CycleData¶

class CycleData¶

Contain all data required for one generated package run.

Create a cycle through ParamGeneratorBase.CreateCycleData(), fill it with parameters and optional constants, and yield it from GenerationIterator or pass it to a callback generator testRunFunction. ParamSet supplies values for package input variables, while ConstSet supplies package constants before the run. The optional Name is shown in the report.

Use AddRecordingInfo() to attach recordings to recording groups, AddMappingItem() for analysis-package mappings, and attributes for additional report data. ParamSet and ConstSet may initially be None; AddParameter() and AddConst() create the corresponding dictionary on first use.

RECORDING_INFO_CLASS¶: alias of RecordingInfo

Attributes¶

Returns additional report attributes for this cycle.

Attribute values are stored as strings and are added or updated through AddAttribute() and UpdateAttribute().

Returns:: Dictionary of additional report attributes.

ConstSet¶

Returns the package constants for this cycle.

The dictionary keys must be valid package constant names. It is None until values are supplied through the constructor or AddConst().

Returns:: Constant dictionary, or None if no constants are set.

Name¶

Return the name displayed for this cycle in the report.

Returns:: Cycle display name.

ParamSet¶

Returns the package input-variable values for this cycle.

The dictionary keys must be valid package input-variable names. It is None until values are supplied through the constructor or AddParameter().

Returns:: Input-variable dictionary, or None if no values are set.

RecordingInfos¶

Returns recording metadata grouped by recording-group name.

Each dictionary value contains the RecordingInfo objects added for that group.

Returns:: Recording metadata grouped by recording-group name.

AddAttribute(name, value)¶

Add an additional attribute to this cycle’s report data.

Attribute names must be unique within the cycle. The value is converted to str. Calling this method with an existing name raises ValueError; use UpdateAttribute() to change an existing attribute.

AddConst(name, value)¶

Add or replace a package constant for this cycle.

name must be a valid package constant name. Supported values are str, float, int, and bool. Calling this method again with the same name replaces the prior value.

AddMappingItem(mappingItem)¶

Add a mapping item to the mapping space for this cycle.

When using analysis packages, also return every mapping item that can be added here from ParamGeneratorBase.GetUsedMappingItems(), so ecu.test can register it before generation.

Parameters:

mappingItem : MappingItem¶: Mapping item created through the Object API mapping interface.

AddParameter(name, value)¶

Add or replace a value for a package input variable.

name must be a valid package input-variable name. Supported values are str, float, int, and bool. Calling this method again with the same name replaces the prior value.

AddRecordingInfo(recordingGroupName, path)¶

Add one recording to a recording group for this cycle.

Reuse recordingGroupName to add multiple recordings to the same group. The returned RecordingInfo represents the recording path and can be configured with its display name, number, type, and format-specific details.

Parameters:

recordingGroupName : str¶: Name of the recording group.
path : str¶: Path to the recording.

Returns:

The recording info object.

Return type:

RecordingInfo

GetAttributes()¶

Returns additional report attributes for this cycle.

Attribute values are stored as strings and are added or updated through AddAttribute() and UpdateAttribute().

Returns:: Dictionary of additional report attributes.
Return type:: dict[str, str]

GetConstSet()¶

Returns the package constants for this cycle.

The dictionary keys must be valid package constant names. It is None until values are supplied through the constructor or AddConst().

Returns:: Constant dictionary, or None if no constants are set.
Return type:: dict | None

GetName()¶

Return the name displayed for this cycle in the report.

Returns:: Cycle display name.
Return type:: str

GetParamSet()¶

Returns the package input-variable values for this cycle.

The dictionary keys must be valid package input-variable names. It is None until values are supplied through the constructor or AddParameter().

Returns:: Input-variable dictionary, or None if no values are set.
Return type:: dict | None

GetRecordingInfos()¶

Returns recording metadata grouped by recording-group name.

Each dictionary value contains the RecordingInfo objects added for that group.

Returns:: Recording metadata grouped by recording-group name.
Return type:: dict[str, list[RecordingInfo]]

SetName(value)¶

Set the name displayed for this cycle in the report.

UpdateAttribute(name, value)¶

Update an existing report attribute.

The value is converted to str. Calling this method with an unknown name raises ValueError; use AddAttribute() to create a new attribute.

OptimizerParamGenerator¶

class OptimizerParamGenerator¶

Base class for callback-based parameter optimization generators.

Derive from this class when an algorithm searches package input values according to package return values. Implement the inherited Generate() method to evaluate candidates through the supplied testRunFunction. Set ID and NAME as for every parameter-set generator and provide optimizer settings through SERIALIZE when they must be persisted.

The class extends CallbackParamGenerator with:

Management of minimum and maximum values for the package parameters
Optional parameter variation before the actual optimization
A dialog for managing minimum and maximum values, parameter variation and optimizer-specific settings

When ENABLE_PARAMETER_VARIATION is True and variation is activated, ecu.test runs it after PreGeneration() and before Generate(). Access its tested input/result pairs through GetVariationResults() inside Generate; they are cleared after Generate finishes. Return parameter bounds from GetMinMaxValues() as {inputVariableName: [minimum, maximum]}. Keys must be package input-variable names, and each bound must contain its lower value before its upper value. The optimizer dialog manages these persisted bounds. The differential-evolution example under examples/AdvancedParametersetGeneratorExamples demonstrates this pattern.

DESCRIPTION : str = ''¶: A short description of the parameter generator.

Info

Setting this field is optional

ENABLE_PARAMETER_VARIATION : bool = True¶

Enables or disables the support of a parameter variation before the optimization starts.

Set this to False when the optimizer does not support a pre-optimization variation. When enabled, users can configure the variation through the optimizer dialog.

ID : str = ''¶: A universally unique identifier to make the parameter generator unique. The ID should be generated using a UUID generator to be unique.

Info

Setting this field is mandatory

NAME : str = ''¶: The display name of the parameter generator.

Info

Setting this field is mandatory

SERIALIZE : dict[str, tuple[str, str] | tuple[str, str, object]] = {}¶

SERIALIZE = {
    'foo': ('FOO-VAR', 'integer', 23),
    'bar': ('BAR', 'string'),
    'params': ('PARAMETERS', 'list'),
}

The declaration key must match the corresponding instance-variable name. For example, an attribute named self.foo requires the key 'foo'. Each value is a tuple with at least two elements:

<variable name>: (<variable alias>, <type alias>, [default value])

Syntax and meaning of the tuple’s elements are:

<variable alias> declares the XML element name used to represent the variable.
<type alias> specifies the Python variable type. The following aliases are supported:
- boolean: bool
- integer: int
- long: int
- float: float
- string: str
- unicode: str

<default value> is an optional element. It specifies the variable’s default value. If the variable’s value equals its default value during export the variable is not exported at all. Conversely, the variable receives its default value during import if the XML data does not provide a value for the variable.

Info

Setting this field is optional

api = None¶: Access to the internal ecu.test API. The API will be assigned at runtime, in order to be independent from ecu.test for testing purposes.

See also

Internal APIs

projectPath : str | None = None¶: Absolute path to the project file containing the generator. In case of direct execution, this is the source project. In case of static generation it is the destination project.

classmethod GetDescription()¶

Returns the description of the parameter generator. The description can be specified by setting the class variable DESCRIPTION.

Returns:: Description text of the parameter generator.
Return type:: str

classmethod GetId()¶

Returns the universally unique identifier of the parameter generator. The identifier should be specified by setting the class variable ID.

Returns:: Unique identifier of the parameter generator.
Return type:: str

classmethod GetName()¶

Returns the name of the parameter generator. The name should be specified by setting the class variable NAME.

Returns:: Display name of the parameter generator.
Return type:: str

Check()¶

Validate the generator configuration before generation.

Return user-visible error messages, or an empty list when the configuration is valid.

Returns:: List of validation error messages.
Return type:: list[str]

Info

Overriding this method is optional.

CreateCycleData(paramSet=None, constSet=None, name=None)¶

Create a CycleData object for one generated package run.

Parameters:

paramSet : dict | None¶: Initial values for package input variables.
constSet : dict | None¶: Initial constants set before the package run.
name : str | None¶: Optional display name for this cycle in the report.

Returns:

Cycle object containing one generated package-run configuration.

Return type:

CycleData

DryGenerationEnabled()¶

Return whether the generator runs in dry generation mode.

In this mode, ecu.test creates static parameter records instead of executing package runs. Runtime constants and package return values are unavailable.

Returns:: True if dry generation mode is active, otherwise False.
Return type:: bool

abstractmethod Generate(testRunFunction)¶

Implement this method to generate and evaluate parameter sets. Each package run must be an instance of CycleData, created with CreateCycleData().

Parameters:

testRunFunction¶: Starts an ecu.test package run for one CycleData instance or a list of instances and returns the corresponding return-variable dictionaries. If ecu.test aborts execution, it raises AbortError. Catch this exception only to release resources, then re-raise it so the package execution remains aborted.

Info

Overriding this method is mandatory

GetDialog()¶

Return a configuration dialog for this parameter-set generator.

The dialog should update this instance’s settings, normally the attributes declared in SERIALIZE. Return None when no configuration UI is required.

Returns:: Configuration dialog instance, or None if no dialog is required.
Return type:: wx.Dialog | None

Info

Overriding this method is optional.

GetLastReturnSets()¶

Return the return-variable dictionaries from the most recent testRunFunction call.

Returns:: Return-variable dictionaries from the latest callback execution.
Return type:: list[dict]

GetMinMaxValues()¶

Return the configured minimum and maximum values for package input parameters.

Use package input-variable names as dictionary keys and a two-item [minimum, maximum] list as each value. The lower value must be first. These bounds are persisted and are available to both the optimizer implementation and its configuration dialog. Example:

{'speed': [100, 120],
 'distance': [1000, 1500]
}

Returns:: Dictionary that maps package input-variable names to [minimum, maximum] bounds.
Return type:: dict

GetParameterText()¶

Return a short summary of the current settings for the properties column.

Returns:: One-line summary text of the current generator settings.
Return type:: str

Info

Overriding this method is optional.

GetReportData()¶

Return custom information for the generator test step in the report.

Return ReportData to populate its value and comment columns. Return None to use the default report content.

Returns:: Custom report data, or None to keep the default report output.
Return type:: ReportData | None

Info

Overriding this method is optional.

GetTargetItemCount()¶

Return the expected number of generated package cycles for progress reporting.

ecu.test can call this method repeatedly while generation is running, so the value is an estimate and may be calculated dynamically.

Returns:: Expected number of generated package cycles.
Return type:: int

GetUsedMappingItems()¶

Return every mapping item used by generated analysis-package parameter sets.

Info

Overriding this method is optional and only necessary for parameter set generators used with analysis packages and overwriting mapping items.

Caution

Returns:: Complete list of mapping items that may be used during generation.
Return type:: list[MappingItem]

GetVariationResults()¶

Return the parameter-variation results as VariationResult objects.

Each result pairs the exact variation CycleData with the corresponding package return values. Results are available only while Generate() runs after an active parameter variation has completed. In all other circumstances, including after Generate returns, this method returns an empty list.

Returns:: List of variation input/result pairs available during active optimizer execution.
Return type:: list[VariationResult]

IsValidForAnalysisPackages()¶

Return whether this parameter-set generator supports analysis packages.

Returns:: True if this generator supports analysis packages, otherwise False.
Return type:: bool

Info

Overriding this method is optional.

OnInit(packageInfo)¶

Process read-only information about the associated package.

Parameters:

packageInfo : PackageInfo¶: Read-only context for the associated package.

Info

Overriding this method is optional

PostGeneration()¶

Clean up after generation.

Info

Overriding this method is optional.

PreGeneration()¶

Prepare generation.

ecu.test calls this method before the specialized generation method. Use it to validate settings, read input files, create expensive resources, or prepare candidate data.

Info

Overriding this method is optional.

class VariationResult¶

Pair the input cycle of one parameter variation with its package return values.

Instances are provided by OptimizerParamGenerator.GetVariationResults() while OptimizerParamGenerator.Generate() runs. CycleData contains the exact parameter values and metadata used for the variation run. ReturnSet contains the result from that same package run and can be None when no result is available.

CycleData¶

Returns the cycle data object that contains the input data for the variation.

Returns:: The cycle data object

ReturnSet¶

Returns the return-variable dictionary from the package execution for this variation.

Returns:: The return set as a dictionary, or None when no result is available.

PackageInfo¶

class PackageInfo¶

Provide read-only context about the package associated with a parameter generator.

ecu.test passes this object to ParamGeneratorBase.OnInit() before configuration or generation begins. Use it to inspect the associated package name, path, and variables. The returned Variable objects distinguish package input parameters from return variables; use those names when constructing CycleData parameter sets.

GetName()¶

Return the package filename without its extension, or None when unavailable.

Returns:: Package filename without extension, or None.
Return type:: str | None

GetParameterVariables()¶

Return descriptors for package input variables used as generated parameters.

Returns:: Sequence of input-variable descriptors.
Return type:: Sequence[Variable]

GetPath()¶

Return the absolute package-file path, or None when unavailable.

Returns:: Absolute package-file path, or None.
Return type:: str | None

GetReturnVariables()¶

Return descriptors for package output variables available after execution.

Returns:: Sequence of output-variable descriptors.
Return type:: Sequence[Variable]

GetVariables()¶

Return read-only descriptors for all variables defined in the package.

Returns:: Sequence of package-variable descriptors.
Return type:: Sequence[Variable]

RecordingInfo¶

class RecordingInfo¶

Describe one recording assigned to a cycle recording group.

Obtain an instance from CycleData.AddRecordingInfo(). The path is mandatory; the optional name, number, type, and format details describe how ecu.test should process the recording. Store several RecordingInfo objects in the same group by calling AddRecordingInfo repeatedly with the same group name.

FormatDetails¶

Returns the format-specific details used to interpret this recording.

Returns:: Format details of the recording.

Path¶

Returns the path to the recording.

Returns:: Path to the recording.

RecordingName¶

Returns the display name of the recording.

Set this when the recording name shown by ecu.test should differ from the filename.

Returns:: Name of the recording.

RecordingNumber¶

Returns the recording number used by the configured recording type.

Returns:: Number of the recording.

RecordingType¶

Returns the recording type used by ecu.test to interpret this recording.

Returns:: Type of the recording.

GetFormatDetails()¶

Returns the format-specific details used to interpret this recording.

Returns:: Format details of the recording.
Return type:: str

GetPath()¶

Returns the path to the recording.

Returns:: Path to the recording.
Return type:: str

GetRecordingName()¶

Returns the display name of the recording.

Set this when the recording name shown by ecu.test should differ from the filename.

Returns:: Name of the recording.
Return type:: str

GetRecordingNumber()¶

Returns the recording number used by the configured recording type.

Returns:: Number of the recording.
Return type:: int

GetRecordingType()¶

Returns the recording type used by ecu.test to interpret this recording.

Returns:: Type of the recording.
Return type:: str

SetFormatDetails(formatDetails)¶

Sets the format details of the recording.

Parameters:

formatDetails : str¶: Format details of the recording.

SetRecordingName(recordingName)¶

Sets the name of the recording.

Parameters:

recordingName : str¶: Name of the recording.

SetRecordingNumber(recordingNumber)¶

Sets the number of the recording.

Parameters:

recordingNumber : int¶: Number of the recording.

SetRecordingType(recordingType)¶

Sets the type of the recording.

Parameters:

recordingType : str¶: Type of the recording.

__init__(path)¶

Initialize the recording metadata.

Parameters:

path : str¶: Path to the recording.

ReportData¶

class ReportData¶

Contain custom value and comment text for the generator test step in the report.

Return an instance from ParamGeneratorBase.GetReportData() when a parameter generator should contribute its own value and comment columns to the report.

Comment¶

Returns the display string for the report comment column.

Returns:: Report comment text.

Value¶

Returns the display string for the report value column.

Returns:: Report value text.

GetComment()¶

Returns the display string for the report comment column.

Returns:: Report comment text.
Return type:: str

GetValue()¶

Returns the display string for the report value column.

Returns:: Report value text.
Return type:: str

SetComment(comment)¶

Sets the display string for the report comment column.

SetValue(value)¶

Sets the display string for the report value column.

Variable¶

class Variable

Provide read-only metadata for a variable defined in the associated package.

Obtain variable descriptors from PackageInfo, typically in OnInit. Use IsInput() to identify variables that can be set through CycleData.ParamSet and IsOutput() to identify values returned after a package run. The descriptor does not modify the package; it exposes its name, declared type, description, and initial value.

Description

Return the package-provided description of this variable.

Returns:: Description text of the package variable.

InitValue

Return the package-defined initial value, whose type depends on VariableType.

Returns:: Initial value configured for this package variable.

Name

Return the package variable name used as a parameter or return-set dictionary key.

Returns:: Package variable name.

VariableType

Return one of the VariableType string constants for this variable.

Returns:: Variable type constant from VariableType.

GetDescription()

Return the package-provided description of this variable.

Returns:: Description text of the package variable.
Return type:: str

GetInitValue()

Return the package-defined initial value, whose type depends on VariableType.

Returns:: Initial value configured for this package variable.
Return type:: object

GetName()

Return the package variable name used as a parameter or return-set dictionary key.

Returns:: Package variable name.
Return type:: str

GetVariableType()

Return one of the VariableType string constants for this variable.

Returns:: Variable type constant from VariableType.
Return type:: str

IsInput()

Return whether the package accepts this variable as a generated input parameter.

Returns:: True if the variable is an input variable.
Return type:: bool

IsOutput()

Return whether this variable is provided as a package return value.

Returns:: True if the variable is an output variable.
Return type:: bool

IsVariable()

Return True to identify this object as a package-variable descriptor.

Returns:: True if this object represents a package variable descriptor.
Return type:: bool

class VariableType

Define the string constants returned by Variable.VariableType.

This class is an enumeration-like namespace, not an instance type. Compare a variable type with these constants when an PackageInfo implementation needs type-specific parameter generation.

UNDEFINED indicates that no specific variable type is assigned. NUMERIC, STRING, ENUM, TEXTTABLE, and BOOL identify numeric, text, enum, text-table, and Boolean package variables respectively.

VariationResult¶

class VariationResult

Pair the input cycle of one parameter variation with its package return values.

CycleData

Returns the cycle data object that contains the input data for the variation.

Returns:: The cycle data object

ReturnSet

Returns the return-variable dictionary from the package execution for this variation.

Returns:: The return set as a dictionary, or None when no result is available.