pyplantsim documentation

Add your content using reStructuredText syntax. See the reStructuredText documentation for details.

class pyplantsim.plantsim.Plantsim(version=PlantsimVersion.V_MJ_22_MI_1, visible=True, trusted=False, license=PlantsimLicense.VIEWER, suppress_3d=False, show_msg_box=False, event_polling_interval=0.05, simulation_finished_callback=None, simtalk_msg_callback=None, fire_simtalk_msg_callback=None, simulation_error_callback=None)

Bases: object

Wrapper class for the Siemens Tecnomatix Plant Simulation COM interface.

Variables:

  • _dispatch_id (str) – COM dispatch identifier for the RemoteControl interface.

  • _event_controller (PlantsimPath) – Path to the event controller.

  • _version (PlantsimVersion or str) – Plant Simulation version to be used.

  • _visible (bool) – Whether the instance window is visible.

  • _trusted (bool) – Whether the instance has access to the computer.

  • _license (PlantsimLicense or str) – License to be used.

  • _suppress_3d (bool) – Suppresses the start of the 3D view.

  • _show_msg_box (bool) – Whether to show a message box.

  • _network_path (str) – Network path.

  • _event_thread (Thread | None) – Event thread object.

  • _event_handler (PlantSimEvents) – Handler for Plant Simulation events.

  • _event_polling_interval (float) – Interval for polling events.

  • _datetime_format (str) – Format for datetime strings.

  • _model_loaded (bool) – Whether a model has been loaded.

  • _model_path (str) – Path to the loaded model.

  • _running (bool) – Simulation status.

  • _simulation_error (dict[str, Any] | None) – Simulation error details.

  • _simulation_finished_event (threading.Event) – Event triggered when the simulation finishes.

  • _error_handler (str | None) – The path to the installed error handler.

  • _user_simulation_finished_cb (Callable[[], None] | None) – Callback for when the simulation finishes.

  • _user_simtalk_msg_cb (Callable[[str], None] | None) – Callback for SimTalk messages.

  • _user_fire_simtalk_msg_cb (Callable[[str], None] | None) – Callback to fire SimTalk messages.

  • _user_simulation_error_cb (Callable[[SimulationException], None] | None) – Callback for simulation errors.

close_console_log_file()

Close routing to the output file.

Return type:

None

close_model()

Close the active model.

Return type:

None

execute_sim_talk(source_code, *parameters)

Execute SimTalk in the current instance and return the result.

Parameters:

  • source_code (str) – The code to be executed.

  • parameters (Any) – Parameters to pass to SimTalk.

Returns:

Result of SimTalk execution.

Return type:

Any

exists_path(path)

Check if the given path exists in the loaded model.

Parameters:

path (PlantsimPath | str) – Path to check.

Returns:

True if path exists, False otherwise.

Return type:

bool

Raises:

Exception – If no model is loaded.

get_abs_sim_time()

Get the current simulation absolute time.

Returns:

Current simulation time.

Return type:

datetime

Raises:

Exception – If EventController is not set.

get_call_cycles()

Run a full simulation with the SimTalk profiler enabled and return the resulting call cycles.

The profiler is activated before the simulation starts and the results are collected once the simulation ends. The model must have an EventController with an end date set.

Returns:

List of call cycles recorded during the simulation run.

Return type:

list[CallCycle]

Raises:

  • SimulationException – If the simulation encounters an error.

  • Exception – If the EventController is not set.

get_current_process_id()

Get the ID of the current instance process.

Returns:

Process ID.

Return type:

int

get_end_time()

Extract the end time of the event controller.

Returns:

Simulation end time as timedelta.

Return type:

timedelta

Raises:

Exception – If EventController is not set.

get_model_language()

Get the model language.

Returns:

Language code (0=German, 1=English, 3=Chinese).

Return type:

int

get_start_date()

Extract the start date from the event controller.

Returns:

Start datetime.

Return type:

datetime

Raises:

Exception – If EventController is not set.

get_table(path)

Get a DataFrame based on a Plant Simulation table object.

Parameters:

path (PlantsimPath) – Path to the table.

Returns:

DataFrame representing the table.

Return type:

DataFrame

get_table_column_data_type(table, column)

Get the data type of a table column.

Parameters:

  • table (PlantsimPath) – Table path.

  • column (int) – Column index.

Returns:

Data type as string.

Return type:

str

get_value(path)

Get the value of an attribute of a Plant Simulation object.

Parameters:

path (PlantsimPath) – Path to the attribute.

Returns:

Attribute value.

Return type:

Any

install_error_handler()

Install an error handler in the model file under basis.ErrorHandler. Searches for any method object and duplicates that.

Raises:

Exception – If error handler could not be created.

Return type:

None

property license: PlantsimLicense | str

License of the current instance.

Returns:

License type.

Return type:

PlantsimLicense | str

load_model(filepath, password=None, close_other=False)

Load a model into the current instance.

Parameters:

  • filepath (str) – Full path to the model file (.spp).

  • password (str | None) – Password for encrypted models.

  • close_other (bool) – Close other models before loading.

Raises:

Exception – If file does not exist or another model is loaded.

Return type:

None

property model_loaded: bool

Whether the instance has a model loaded.

Returns:

True if model is loaded, False otherwise.

Return type:

bool

property model_path: str | None

Path to the current model file.

Returns:

Model path or None.

Return type:

str | None

property network_path: PlantsimPath | None

Current active network path.

Returns:

Network path or None.

Return type:

str | None

new_model(close_other=False)

Create a new simulation model in the current instance.

Parameters:

close_other (bool) – Close other models before creating new one.

Return type:

None

open_console_log_file(filepath)

Route the Console output to a file.

Parameters:

filepath (str) – Path to the log file.

Return type:

None

quit()

Quit the current Plant Simulation instance.

Raises:

Exception – If instance is already closed.

Return type:

None

quit_after_time(time)

Quit the current instance after a specified time.

Parameters:

time (int) – Time in seconds after which instance quits.

Return type:

None

read_call_cycles(max_num_cycles=None)

Read the call cycles currently stored in the model’s profiler without running a new simulation.

This is useful when the profiler has already been activated externally, or when calling from within an on_endsim callback. For a self-contained profiling run use get_call_cycles() instead.

Parameters:

max_num_cycles (int | None) – Maximum number of call cycles to retrieve. If None, all available cycles are returned.

Returns:

List of call cycles from the profiler output.

Return type:

list[CallCycle]

Raises:

SimulationException – If the SimTalk script execution fails.

register_on_fire_simtalk_message(callback)

Set callback for FireSimTalkMessage event.

Parameters:

callback (Optional[Callable[[str], None]]) – Callback function.

Return type:

None

register_on_simtalk_message(callback)

Set callback for OnSimTalkMessage event.

Parameters:

callback (Optional[Callable[[str], None]]) – Callback function.

Return type:

None

register_on_simulation_error(callback)

Set callback for simulation errors.

Parameters:

callback (Optional[Callable[[SimulationException], None]]) – Callback function.

Return type:

None

register_on_simulation_finished(callback)

Set callback for OnSimulationFinished event.

Parameters:

callback (Optional[Callable[[], None]]) – Callback function.

Return type:

None

remove_error_handler()

Remove the installed error handler from basis.ErrorHandler.

Raises:

Exception – If no error handler is installed or removal fails.

Return type:

None

reset_simulation()

Reset the simulation.

Raises:

Exception – If EventController is not set.

Return type:

None

restart()

Restart the Plant Simulation instance and restore previous state.

Raises:

NotImplementedError – Restart is not implemented.

Return type:

None

run_simulation(without_animation=True, on_init=None, on_endsim=None, on_simulation_error=None, on_progress=None, cancel_event=None)

Run a full simulation and return after the run is over. This method suggests, that the EventController has a EndDate

Parameters:

  • without_animation (bool) – Run without animation.

  • on_init (Optional[Callable[[Plantsim], None]]) – Callback before simulation starts.

  • on_endsim (Optional[Callable[[Plantsim], None]]) – Callback after simulation ends.

  • on_simulation_error (Optional[Callable[[Plantsim, SimulationException], None]]) – Callback on simulation error.

  • on_progress (Optional[Callable[[Plantsim, float], None]]) – Progress callback (receives percent complete).

  • cancel_event (Event | None) – Event to cancel the run.

Raises:

SimulationException – If a simulation error occurs.

Return type:

None

save_model(folder_path, file_name)

Save the current model under the given name in the given folder.

Parameters:

  • folder_path (str) – Path to the folder.

  • file_name (str) – Name of the model.

Return type:

None

set_event_controller(path=None)

Set the path of the Event Controller.

Parameters:

path (PlantsimPath | None) – Path to the EventController object. If not given, uses default.

Return type:

None

set_license(license, force=False)

Set the license for the instance.

Parameters:

  • license (PlantsimLicense | str) – License type.

  • force (bool) – Force update even if value is already set.

Return type:

None

set_network(path, set_event_controller=False, install_error_handler=False)

Set the active network.

Parameters:

  • path (PlantsimPath) – Network path.

  • set_event_controller (bool) – Whether to set the event controller.

  • install_error_handler (bool) – Whether to install the error handler.

Return type:

None

set_seed(seed)

Set the random seed on the event controller.

Parameters:

seed (int) – Seed value (-2147483647 to 2147483647).

Raises:

Exception – If EventController is not set or seed is out of range.

Return type:

None

set_show_message_box(show, force=False)

Set whether the instance should show a message box.

Parameters:

  • show (bool) – Show message box.

  • force (bool) – Force update even if value is already set.

Return type:

None

set_suppress_start_of_3d(suppress, force=False)

Set whether to suppress the start of 3D.

Parameters:

  • suppress (bool) – Suppress 3D view.

  • force (bool) – Force update even if value is already set.

Return type:

None

set_table(path, df)

Set a Plant Simulation table based on a DataFrame.

Parameters:

  • path (PlantsimPath) – Path to the table.

  • df (DataFrame) – DataFrame containing the values to write.

Return type:

None

set_trust_models(trusted, force=False)

Set whether the instance has access to the computer.

Parameters:

  • trusted (bool) – Trusted mode.

  • force (bool) – Force update even if value is already set.

Return type:

None

set_value(path, value)

Set a value to a given attribute.

Parameters:

  • path (PlantsimPath) – Path to the attribute.

  • value (Any) – The new value to assign.

Return type:

None

set_version(version)

Set the Plant Simulation version.

Parameters:

version (PlantsimVersion | str) – Plant Simulation version or string.

Return type:

None

set_visible(visible, force=False)

Set whether the instance window is visible.

Parameters:

  • visible (bool) – Window visibility.

  • force (bool) – Force update even if value is already set.

Return type:

None

property show_msg_box: bool

Whether the instance is showing a message box.

Returns:

True if message box is shown, False otherwise.

Return type:

bool

property simulation_running: bool

Whether the simulation is currently running.

Returns:

True if running, False otherwise.

Return type:

bool

start()

Start the Plant Simulation instance.

Raises:

Exception – If Plant Simulation is already running.

Returns:

The PlantSim instance.

Return type:

Plantsim

start_simulation(without_animation=False)

Start the simulation.

Parameters:

without_animation (bool) – Run without animation.

Raises:

Exception – If EventController is not set.

Return type:

None

stop()

Stop the Plant Simulation instance and clean up resources.

Return type:

None

stop_simulation()

Stop the simulation.

Raises:

Exception – If EventController is not set.

Return type:

None

property suppress_3d: bool

Whether suppression of 3D is enabled.

Returns:

True if suppressed, False otherwise.

Return type:

bool

property trusted: bool

Whether the instance is trusted.

Returns:

True if trusted, False otherwise.

Return type:

bool

property version: Version

Version of the current instance.

Returns:

Plant Simulation version.

Return type:

Version

property visible: bool

Whether the instance is visible.

Returns:

True if visible, False otherwise.

Return type:

bool