"""Modelica model linearization results.

n: int

m: int

p: int

A: list

B: list

C: list

D: list

x0: list[float]

u0: list[float]

stateVars: list[str]

inputVars: list[str]

outputVars: list[str]

def __iter__(self):

"""Allow unpacking A, B, C, D = result."""

yield self.A

yield self.B

yield self.C

yield self.D

def __getitem__(self, index: int):

"""Allow accessing A, B, C, D via result[0] through result[3].

"""

def __init__(

self,

session: OMCSession,

runpath: OMCPath,

modelname: Optional[str] = None,

) -> None:

if modelname is None:

raise ModelicaSystemError("Missing model name!")

self._session = session

self._runpath = runpath

self._model_name = modelname

# dictionaries of command line arguments for the model executable

self._args: dict[str, str | None] = {}

# 'override' argument needs special handling

self._arg_override: dict[str, str] = {}

def arg_set(

self,

key: str,

val: Optional[str | dict[str, Any] | numbers.Number] = None,

) -> None:

"""

def override2str(

okey: str,

oval: str | bool | numbers.Number,

) -> str:

"""

if isinstance(oval, str):

try:

oval_evaluated = ast.literal_eval(oval)

if isinstance(oval_evaluated, (numbers.Number, bool)):

oval = oval_evaluated

except (ValueError, SyntaxError):

pass

if isinstance(oval, str):

oval_str = oval.strip()

elif isinstance(oval, bool):

oval_str = 'true' if oval else 'false'

elif isinstance(oval, numbers.Number):

oval_str = str(oval)

else:

raise ModelicaSystemError(f"Invalid value for override key {okey}: {type(oval)}")

return f"{okey}={oval_str}"

if not isinstance(key, str):

raise ModelicaSystemError(f"Invalid argument key: {repr(key)} (type: {type(key)})")

key = key.strip()

if isinstance(val, dict):

if key != 'override':

raise ModelicaSystemError("Dictionary input only possible for key 'override'!")

for okey, oval in val.items():

if not isinstance(okey, str):

raise ModelicaSystemError("Invalid key for argument 'override': "

f"{repr(okey)} (type: {type(okey)})")

if not isinstance(oval, (str, bool, numbers.Number, type(None))):

raise ModelicaSystemError(f"Invalid input for 'override'.{repr(okey)}: "

f"{repr(oval)} (type: {type(oval)})")

if okey in self._arg_override:

if oval is None:

logger.info(f"Remove model executable override argument: {repr(self._arg_override[okey])}")

del self._arg_override[okey]

continue

logger.info(f"Update model executable override argument: {repr(okey)} = {repr(oval)} "

f"(was: {repr(self._arg_override[okey])})")

if oval is not None:

self._arg_override[okey] = override2str(okey=okey, oval=oval)

argval = ','.join(sorted(self._arg_override.values()))

elif val is None:

argval = None

elif isinstance(val, str):

argval = val.strip()

elif isinstance(val, numbers.Number):

argval = str(val)

else:

raise ModelicaSystemError(f"Invalid argument value for {repr(key)}: {repr(val)} (type: {type(val)})")

if key in self._args:

logger.warning(f"Override model executable argument: {repr(key)} = {repr(argval)} "

f"(was: {repr(self._args[key])})")

self._args[key] = argval

def arg_get(self, key: str) -> Optional[str | dict[str, str | bool | numbers.Number]]:

"""

if key in self._args:

return self._args[key]

return None

def args_set(

self,

args: dict[str, Optional[str | dict[str, Any] | numbers.Number]],

) -> None:

"""

for arg in args:

self.arg_set(key=arg, val=args[arg])

def get_cmd_args(self) -> list[str]:

"""

cmdl = []

for key in sorted(self._args):

if self._args[key] is None:

cmdl.append(f"-{key}")

else:

cmdl.append(f"-{key}={self._args[key]}")

return cmdl

def definition(self) -> OMCSessionRunData:

"""

# ensure that a result filename is provided

result_file = self.arg_get('r')

if not isinstance(result_file, str):

result_file = (self._runpath / f"{self._model_name}.mat").as_posix()

omc_run_data = OMCSessionRunData(

cmd_path=self._runpath.as_posix(),

cmd_model_name=self._model_name,

cmd_args=self.get_cmd_args(),

cmd_result_path=result_file,

)

omc_run_data_updated = self._session.omc_run_data_update(

omc_run_data=omc_run_data,

)

return omc_run_data_updated

@staticmethod

def parse_simflags(simflags: str) -> dict[str, Optional[str | dict[str, Any] | numbers.Number]]:

"""

warnings.warn("The argument 'simflags' is depreciated and will be removed in future versions; "

"please use 'simargs' instead", DeprecationWarning, stacklevel=2)

simargs: dict[str, Optional[str | dict[str, Any] | numbers.Number]] = {}

args = [s for s in simflags.split(' ') if s]

for arg in args:

if arg[0] != '-':

raise ModelicaSystemError(f"Invalid simulation flag: {arg}")

arg = arg[1:]

parts = arg.split('=')

if len(parts) == 1:

simargs[parts[0]] = None

elif parts[0] == 'override':

override = '='.join(parts[1:])

override_dict = {}

for item in override.split(','):

kv = item.split('=')

if not 0 < len(kv) < 3:

raise ModelicaSystemError(f"Invalid value for '-override': {override}")

if kv[0]:

try:

override_dict[kv[0]] = kv[1]

except (KeyError, IndexError) as ex:

raise ModelicaSystemError(f"Invalid value for '-override': {override}") from ex

simargs[parts[0]] = override_dict

"""

def __init__(

self,

command_line_options: Optional[list[str]] = None,

work_directory: Optional[str | os.PathLike] = None,

omhome: Optional[str] = None,

session: Optional[OMCSession] = None,

) -> None:

"""Create a ModelicaSystem instance. To define the model use model() or convertFmu2Mo().

# Initialize base class

super().__init__()

self._linearized_inputs: list[str] = [] # linearization input list

self._linearized_outputs: list[str] = [] # linearization output list

self._linearized_states: list[str] = [] # linearization states list

if session is not None:

self._session = session

else:

self._session = OMCSessionLocal(omhome=omhome)

# get OpenModelica version

self._version = self._session.sendExpression("getVersion()", parsed=True)

# set commandLineOptions using default values or the user defined list

if command_line_options is None:

# set default command line options to improve the performance of linearization and to avoid recompilation if

# the simulation executable is reused in linearize() via the runtime flag '-l'

command_line_options = [

"--linearizationDumpLanguage=python",

"--generateSymbolicLinearization",

]

for opt in command_line_options:

self.set_command_line_options(command_line_option=opt)

self._simulated = False # True if the model has already been simulated

self._result_file: Optional[OMCPath] = None # for storing result file

self._work_dir: OMCPath = self.setWorkDirectory(work_directory)

self._model_name: Optional[str] = None

self._libraries: Optional[list[str | tuple[str, str]]] = None

self._file_name: Optional[OMCPath] = None

self._variable_filter: Optional[str] = None

def model(

self,

model_name: Optional[str] = None,

model_file: Optional[str | os.PathLike] = None,

libraries: Optional[list[str | tuple[str, str]]] = None,

variable_filter: Optional[str] = None,

build: bool = True,

) -> None:

"""Load and build a Modelica model.

if self._model_name is not None:

raise ModelicaSystemError("Can not reuse this instance of ModelicaSystem "

f"defined for {repr(self._model_name)}!")

if model_name is None or not isinstance(model_name, str):

raise ModelicaSystemError("A model name must be provided!")

if libraries is None:

libraries = []

if not isinstance(libraries, list):

raise ModelicaSystemError(f"Invalid input type for libraries: {type(libraries)} - list expected!")

# set variables

self._model_name = model_name # Model class name

self._libraries = libraries # may be needed if model is derived from other model

self._variable_filter = variable_filter

if self._libraries:

self._loadLibrary(libraries=self._libraries)

self._file_name = None

if model_file is not None:

file_path = pathlib.Path(model_file)

# special handling for OMCProcessLocal - consider a relative path

if isinstance(self._session, OMCSessionLocal) and not file_path.is_absolute():

file_path = pathlib.Path.cwd() / file_path

if not file_path.is_file():

raise IOError(f"Model file {file_path} does not exist!")

self._file_name = self.getWorkDirectory() / file_path.name

if (isinstance(self._session, OMCSessionLocal)

and file_path.as_posix() == self._file_name.as_posix()):

pass

elif self._file_name.is_file():

raise IOError(f"Simulation model file {self._file_name} exist - not overwriting!")

else:

content = file_path.read_text(encoding='utf-8')

self._file_name.write_text(content)

if self._file_name is not None:

self._loadFile(fileName=self._file_name)

if build:

self.buildModel(variable_filter)

def get_session(self) -> OMCSession:

"""

return self._session

def set_command_line_options(self, command_line_option: str):

"""

exp = f'setCommandLineOptions("{command_line_option}")'

self.sendExpression(exp)

def _loadFile(self, fileName: OMCPath):

# load file

self.sendExpression(f'loadFile("{fileName.as_posix()}")')

# for loading file/package, loading model and building model

def _loadLibrary(self, libraries: list):

# load Modelica standard libraries or Modelica files if needed

for element in libraries:

if element is not None:

if isinstance(element, str):

if element.endswith(".mo"):

api_call = "loadFile"

else:

api_call = "loadModel"

self._requestApi(apiName=api_call, entity=element)

elif isinstance(element, tuple):

if not element[1]:

expr_load_lib = f"loadModel({element[0]})"

else:

expr_load_lib = f'loadModel({element[0]}, {{"{element[1]}"}})'

self.sendExpression(expr_load_lib)

else:

raise ModelicaSystemError("loadLibrary() failed, Unknown type detected: "

f"{element} is of type {type(element)}, "

"The following patterns are supported:\n"

'1)["Modelica"]\n'

'2)[("Modelica","3.2.3"), "PowerSystems"]\n')

def setWorkDirectory(self, work_directory: Optional[str | os.PathLike] = None) -> OMCPath:

"""

if work_directory is not None:

workdir = self._session.omcpath(work_directory).absolute()

if not workdir.is_dir():

raise IOError(f"Provided work directory does not exists: {work_directory}!")

else:

workdir = self._session.omcpath_tempdir().absolute()

if not workdir.is_dir():

raise IOError(f"{workdir} could not be created")

logger.info("Define work dir as %s", workdir)

exp = f'cd("{workdir.as_posix()}")'

self.sendExpression(exp)

# set the class variable _work_dir ...

self._work_dir = workdir

# ... and also return the defined path

return workdir

def getWorkDirectory(self) -> OMCPath:

"""

return self._work_dir

def buildModel(self, variableFilter: Optional[str] = None):

filter_def: Optional[str] = None

if variableFilter is not None:

filter_def = variableFilter

elif self._variable_filter is not None:

filter_def = self._variable_filter

if filter_def is not None:

var_filter = f'variableFilter="{filter_def}"'

else:

var_filter = 'variableFilter=".*"'

build_model_result = self._requestApi(apiName="buildModel", entity=self._model_name, properties=var_filter)

logger.debug("OM model build result: %s", build_model_result)

# check if the executable exists ...

om_cmd = ModelicaSystemCmd(

session=self._session,

runpath=self.getWorkDirectory(),

modelname=self._model_name,

)

# ... by running it - output help for command help

om_cmd.arg_set(key="help", val="help")

cmd_definition = om_cmd.definition()

returncode = self._session.run_model_executable(cmd_run_data=cmd_definition)

if returncode != 0:

raise ModelicaSystemError("Model executable not working!")

xml_file = self._session.omcpath(build_model_result[0]).parent / build_model_result[1]

self._xmlparse(xml_file=xml_file)

def sendExpression(self, expr: str, parsed: bool = True) -> Any:

try:

retval = self._session.sendExpression(expr, parsed)

except OMCSessionException as ex:

raise ModelicaSystemError(f"Error executing {repr(expr)}: {ex}") from ex

logger.debug(f"Result of executing {repr(expr)}: {textwrap.shorten(repr(retval), width=100)}")

return retval

# request to OMC

def _requestApi(

self,

apiName: str,

entity: Optional[str] = None,

properties: Optional[str] = None,

) -> Any:

if entity is not None and properties is not None:

exp = f'{apiName}({entity}, {properties})'

elif entity is not None and properties is None:

if apiName in ("loadFile", "importFMU"):

exp = f'{apiName}("{entity}")'

else:

exp = f'{apiName}({entity})'

else:

exp = f'{apiName}()'

return self.sendExpression(exp)

def _xmlparse(self, xml_file: OMCPath):

if not xml_file.is_file():

raise ModelicaSystemError(f"XML file not generated: {xml_file}")

# ModelicaSystem uses OMCPath to read text, then fromstring

xml_content = xml_file.read_text()

tree = ET.ElementTree(ET.fromstring(xml_content))

root = tree.getroot()

# Delegate population to base class

self._populate_from_xml_root(root)

def getContinuous(

self,

names: Optional[Union[str, list[str]]] = None,

) -> Union[dict[str, Union[str, numbers.Real]], list[Union[str, numbers.Real]]]:

"""Get values of continuous signals.

if not self._simulated:

return super().getContinuous(names)

if names is None:

for name in self._continuous:

try:

value = self.getSolutions(name)

self._continuous[name] = value[0][-1]

except (OMCSessionException, ModelicaSystemError) as ex:

raise ModelicaSystemError(f"{name} could not be computed") from ex

return self._continuous

if isinstance(names, str):

if names in self._continuous:

value = self.getSolutions(names)

self._continuous[names] = value[0][-1]

return [self._continuous[names]]

raise ModelicaSystemError(f"{names} is not continuous")

if isinstance(names, list):

valuelist = []

for name in names:

if name in self._continuous:

value = self.getSolutions(name)

self._continuous[name] = value[0][-1]

valuelist.append(value[0][-1])

else:

raise ModelicaSystemError(f"{name} is not continuous")

return valuelist

raise ModelicaSystemError("Unhandled input for getContinous()")

def getOutputs(

self,

names: Optional[Union[str, list[str]]] = None,

) -> Union[dict[str, Union[str, numbers.Real]], list[Union[str, numbers.Real]]]:

"""Get values of output signals.

if not self._simulated:

return super().getOutputs(names)

if names is None:

for name in self._outputs:

value = self.getSolutions(name)

self._outputs[name] = value[0][-1]

return self._outputs

if isinstance(names, str):

if names in self._outputs:

value = self.getSolutions(names)

self._outputs[names] = value[0][-1]

return [self._outputs[names]]

raise KeyError(names)

if isinstance(names, list):

valuelist = []

for name in names:

if name in self._outputs:

value = self.getSolutions(name)

self._outputs[name] = value[0][-1]

valuelist.append(value[0][-1])

else:

raise KeyError(name)

return valuelist

raise ModelicaSystemError("Unhandled input for getOutputs()")

def getLinearizationOptions(

self,

names: Optional[Union[str, list[str]]] = None,

) -> Union[dict[str, Union[str, float]], list[Union[str, float]]]:

"""Get simulation options used for linearization.

if names is None:

return self._linearization_options

if isinstance(names, str):

return [self._linearization_options[names]]

if isinstance(names, list):

return [self._linearization_options[x] for x in names]

raise ModelicaSystemError("Unhandled input for getLinearizationOptions()")

def parse_om_version(self, version: str) -> tuple[int, int, int]:

match = re.search(r"v?(\d+)\.(\d+)\.(\d+)", version)

if not match:

raise ValueError(f"Version not found in: {version}")

major, minor, patch = map(int, match.groups())

return major, minor, patch

def simulate_cmd(

self,

result_file: OMCPath,

simflags: Optional[str] = None,

simargs: Optional[dict[str, Optional[str | dict[str, Any] | numbers.Number]]] = None,

) -> ModelicaSystemCmd:

"""

om_cmd = ModelicaSystemCmd(

session=self._session,

runpath=self.getWorkDirectory(),

modelname=self._model_name,

)

# always define the result file to use

om_cmd.arg_set(key="r", val=result_file.as_posix())

# allow runtime simulation flags from user input

if simflags is not None:

om_cmd.args_set(args=om_cmd.parse_simflags(simflags=simflags))

if simargs:

om_cmd.args_set(args=simargs)

if self._override_variables or self._simulate_options_override:

override_file = result_file.parent / f"{result_file.stem}_override.txt"

# simulation options are not read from override file from version >= 1.26.0,

# pass them to simulation executable directly as individual arguments

# see https://github.com/OpenModelica/OpenModelica/pull/14813

major, minor, patch = self.parse_om_version(self._version)

if (major, minor, patch) >= (1, 26, 0):

for key, opt_value in self._simulate_options_override.items():

om_cmd.arg_set(key=key, val=str(opt_value))

override_content = (

"\n".join([f"{key}={value}" for key, value in self._override_variables.items()])

+ "\n"

)

else:

override_content = (

"\n".join([f"{key}={value}" for key, value in self._override_variables.items()])

+ "\n".join([f"{key}={value}" for key, value in self._simulate_options_override.items()])

+ "\n"

)

override_file.write_text(override_content)

om_cmd.arg_set(key="overrideFile", val=override_file.as_posix())

if self._inputs: # if model has input quantities

for key, val in self._inputs.items():

if val is None:

val = [(float(self._simulate_options["startTime"]), 0.0),

(float(self._simulate_options["stopTime"]), 0.0)]

self._inputs[key] = val

if float(self._simulate_options["startTime"]) != val[0][0]:

raise ModelicaSystemError(f"startTime not matched for Input {key}!")

if float(self._simulate_options["stopTime"]) != val[-1][0]:

raise ModelicaSystemError(f"stopTime not matched for Input {key}!")

# csvfile is based on name used for result file

csvfile = result_file.parent / f"{result_file.stem}.csv"

# write csv file and store the name

csvfile = self._createCSVData(csvfile=csvfile)

om_cmd.arg_set(key="csvInput", val=csvfile.as_posix())

return om_cmd

def simulate(

self,

resultfile: Optional[str | os.PathLike] = None,

simflags: Optional[str] = None,

simargs: Optional[dict[str, Optional[str | dict[str, Any] | numbers.Number]]] = None,

) -> None:

"""Simulate the model according to simulation options.

if resultfile is None:

# default result file generated by OM

self._result_file = self.getWorkDirectory() / f"{self._model_name}_res.mat"

elif isinstance(resultfile, OMCPath):

self._result_file = resultfile

else:

self._result_file = self._session.omcpath(resultfile)

if not self._result_file.is_absolute():

self._result_file = self.getWorkDirectory() / resultfile

if not isinstance(self._result_file, OMCPath):

raise ModelicaSystemError(f"Invalid result file path: {self._result_file} - must be an OMCPath object!")

om_cmd = self.simulate_cmd(

result_file=self._result_file,

simflags=simflags,

simargs=simargs,

)

# delete resultfile ...

if self._result_file.is_file():

self._result_file.unlink()

# ... run simulation ...

cmd_definition = om_cmd.definition()

returncode = self._session.run_model_executable(cmd_run_data=cmd_definition)

# and check returncode *AND* resultfile

if returncode != 0 and self._result_file.is_file():

# check for an empty (=> 0B) result file which indicates a crash of the model executable

# see: https://github.com/OpenModelica/OMPython/issues/261

# https://github.com/OpenModelica/OpenModelica/issues/13829

if self._result_file.size() == 0:

self._result_file.unlink()

raise ModelicaSystemError("Empty result file - this indicates a crash of the model executable!")

logger.warning(f"Return code = {returncode} but result file exists!")

self._simulated = True

def plot(

self,

plotdata: str,

resultfile: Optional[str | os.PathLike] = None,

) -> None:

"""

if not isinstance(self._session, OMCSessionLocal):

raise ModelicaSystemError("Plot is using the OMC plot functionality; "

"thus, it is only working if OMC is running locally!")

if resultfile is not None:

plot_result_file = self._session.omcpath(resultfile)

elif self._result_file is not None:

plot_result_file = self._result_file

else:

raise ModelicaSystemError("No resultfile available - either run simulate() before plotting "

"or provide a result file!")

if not plot_result_file.is_file():

raise ModelicaSystemError(f"Provided resultfile {repr(plot_result_file.as_posix())} does not exists!")

expr = f'plot({plotdata}, fileName="{plot_result_file.as_posix()}")'

self.sendExpression(expr=expr)

def getSolutions(

self,

varList: Optional[str | list[str]] = None,

resultfile: Optional[str | os.PathLike] = None,

) -> tuple[str] | np.ndarray:

"""Extract simulation results from a result data file.

if resultfile is None:

if self._result_file is None:

raise ModelicaSystemError("No result file found. Run simulate() first.")

result_file = self._result_file

else:

result_file = self._session.omcpath(resultfile)

# check if the result file exits

if not result_file.is_file():

raise ModelicaSystemError(f"Result file does not exist {result_file.as_posix()}")

# get absolute path

result_file = result_file.absolute()

result_vars = self.sendExpression(f'readSimulationResultVars("{result_file.as_posix()}")')

self.sendExpression("closeSimulationResultFile()")

if varList is None:

return result_vars

if isinstance(varList, str):

var_list_checked = [varList]

elif isinstance(varList, list):

var_list_checked = varList

else:

raise ModelicaSystemError("Unhandled input for getSolutions()")

for var in var_list_checked:

if var == "time":

continue

if var not in result_vars:

raise ModelicaSystemError(f"Requested data {repr(var)} does not exist")