Deprecate structual parameters keyword

[HvanderStok]

Deprecate structural_parameters keyword in DymolaAPI.simulate()

Description

The structural_parameters keyword argument in DymolaAPI.simulate() should be deprecated in favor of writing Modelica modifiers directly in the model name.

Current behavior

Users can pass structural parameters as a keyword argument, which internally triggers _alter_model_name to build a modifier and re-translate the model on every simulation call:

sim_api.simulate(
    parameters={"parameterPipe": "AixLib.DataBase.Pipes.PE_X.DIN_16893_SDR11_d160()"},
    structural_parameters=["parameterPipe"]
)

Problems

• The internal _alter_model_name mechanism is fragile — it matches parameter names against self.states as a heuristic, which can miss parameters or produce incorrect modifiers.
• It re-translates the model on every simulation call, which is slow and produces a warning telling the user to add annotation(Evaluate=false) anyway.
• The interaction between structural_parameters, modify_structural_parameters, and unsupported_parameters in _single_simulation adds significant complexity to a critical code path.
• Users need to understand both the keyword argument and the underlying Modelica modifier concept, when just understanding modifiers is sufficient.

Preferred approach

Write the modifier directly in the model name. This is already demonstrated in the existing e5_modifier_example example and is clearer, more transparent, and easier to debug:

model_name = 'MyPackage.MyModel(parameterPipe=AixLib.DataBase.Pipes.PE_X.DIN_16893_SDR11_d160())'
sim_api = DymolaAPI(model_name=model_name, ...)

Or use the model_names keyword to simulate multiple modified variants:

results = sim_api.simulate(
    model_names=[
        "MyPackage.MyModel(myParam=1)",
        "MyPackage.MyModel(myParam=2)",
    ]
)

Proposed plan

• 1. Add a FutureWarning when structural_parameters is passed to simulate().
• 2. Add a FutureWarning when modify_structural_parameters is explicitly set in the constructor.
• 3. Update documentation and examples to use the modifier approach.
• 4. Remove structural_parameters, modify_structural_parameters, and _alter_model_name in the next major release.

Related

• The new basic Dymola workflow example (Issue Add simple Dymola example #175) will demonstrate the modifier approach as the recommended pattern. I will also add the warnings with the PR to this Issue.