libmuscle.instance module

class libmuscle.instance.Instance(ports: ~typing.Dict[~ymmsl.component.Operator, ~typing.List[str]] | None = None, flags: ~libmuscle.instance.InstanceFlags = InstanceFlags.None)[source]

Bases: object

Represents a component instance in a MUSCLE3 simulation.

This class provides a low-level send/receive API for the instance to use.

error_shutdown(message: str) → None[source]

Logs an error and shuts down the Instance.

If you detect that something is wrong (invalid input, invalid settings, simulation diverged, or anything else really), you should call this method before calling exit() or raising an exception that you don’t expect to catch.

If you do so, the Instance will tell the rest of the simulation that it encountered an error and will shut down. That makes it easier to debug the situation (the message will be logged), and it reduces the chance that other parts of the simulation will sit around waiting forever for a message that this instance was supposed to send.

Parameters:

message – An error message describing the problem.

get_port_length(port: str) → int[source]

Returns the current length of the port.

Parameters:

port – The name of the port to measure.

Raises:

RuntimeError – If this is a scalar port.

get_setting(name: str, typ: typing_extensions.Literal[str]) → str[source]
get_setting(name: str, typ: typing_extensions.Literal[int]) → int
get_setting(name: str, typ: typing_extensions.Literal[float]) → float
get_setting(name: str, typ: typing_extensions.Literal[bool]) → bool
get_setting(name: str, typ: typing_extensions.Literal[[float]]) → List[float]
get_setting(name: str, typ: typing_extensions.Literal[[[float]]]) → List[List[float]]
get_setting(name: str, typ: None = None) → str | int | float | bool | List[float] | List[List[float]] | bool_union_fix

Returns the value of a model setting.

Parameters:

  • name – The name of the setting, without any instance prefix.

  • typ – The expected type of the value. If the value does not match this type, a TypeError will be raised. If not specified, any of the supported types will be accepted, and you’ll have to figure out what you got yourself.

Raises:

  • KeyError – If no value was set for this setting.

  • TypeError – If the type of the setting’s value was not as expected.

is_connected(port: str) → bool[source]

Returns whether the given port is connected.

Parameters:

port – The name of the port to inspect.

Returns:

True if there is a conduit attached to this port, False if not.

is_resizable(port: str) → bool[source]

Returns whether the given port is resizable.

Scalar ports are never resizable. Whether a vector port is resizable depends on what it is connected to.

Parameters:

port – Name of the port to inspect.

Returns:

True if the port can be resized.

is_vector_port(port: str) → bool[source]

Returns whether a port is a vector or scalar port

If a port has been declared to be a vector port (i.e. the name passed when creating this Instance had ‘[]’ at the end), then you can pass a ‘slot’ argument when sending or receiving. It’s like the port is a vector of slots on which you can send or receive messages.

This function returns True if the given port is a vector port, and False if it is a scalar port.

Parameters:

port – The port to check this property of.

list_ports() → Dict[Operator, List[str]][source]

Returns a description of the ports that this Instance has.

Note that the result has almost the same format as the port declarations you pass when making an Instance. The only difference is that the port names never have [] at the end, even if the port is a vector port.

Returns:

A dictionary, indexed by Operator, containing lists of port names. Operators with no associated ports are not included.

list_settings() → List[str][source]

List settings by name.

This function returns a list of names of the available settings.

Returns:

A list of setting names.

load_snapshot() → Message[source]

Load a snapshot.

Must only be called when resuming() returns True.

Returns:

Message object containing the state as saved in a previous run through save_snapshot() or save_final_snapshot().

Raises:

RuntimeError – if not resuming from a snapshot.

receive(port_name: str, slot: int | None = None, default: Message | None = None) → Message[source]

Receive a message from the outside world.

Receiving is a blocking operation. This function will contact the sender, wait for a message to be available, and receive and return it.

If the port you are receiving on is not connected, the default value you specified will be returned exactly as you passed it. If you didn’t specify a default value (e.g. because there is no reasonable default, you really need the outside input) and the port is not connected, you’ll get a RuntimeError.

Parameters:

  • port_name – The endpoint on which a message is to be received.

  • slot – The slot to receive the message on, if any.

  • default – A default value to return if this port is not connected.

Returns:

The received message. The settings attribute of the received message will be None.

Raises:

RuntimeError – If the given port is not connected and no default value was given.

receive_with_settings(port_name: str, slot: int | None = None, default: Message | None = None) → Message[source]

Receive a message with attached settings overlay.

This function should not be used in submodels. It is intended for use by special component that are ensemble-aware and have to pass on overlay settings explicitly.

Receiving is a blocking operation. This function will contact the sender, wait for a message to be available, and receive and return it.

If the port you are receiving on is not connected, the default value you specified will be returned exactly as you passed it. If you didn’t specify a default value (e.g. because there is no reasonable default, and you really need the outside input) and the port is not connected, then you’ll get a RuntimeError.

Parameters:

  • port_name – The endpoint on which a message is to be received.

  • slot – The slot to receive the message on, if any.

  • default – A default value to return if this port is not connected.

Returns:

The received message. The settings attribute will contain the received Settings, and will not be None.

Raises:

RuntimeError – If the given port is not connected and no default value was given.

resuming() → bool[source]

Check if this instance is resuming from a snapshot.

Must be used by submodels that implement the checkpointing API. You’ll get a RuntimeError when not calling this method in an iteration of the reuse loop.

This method returns True for the first iteration of the reuse loop after resuming from a previously taken snapshot. When resuming from a snapshot, the submodel must load its state from the snapshot as returned by load_snapshot().

Returns:

True iff the submodel must resume from a snapshot.

reuse_instance() → bool[source]

Decide whether to run this instance again.

In a multiscale simulation, instances get reused all the time. For example, in a macro-micro simulation, the micromodel does a complete run for every timestep of the macromodel. Rather than starting up a new instance of the micromodel, which could be expensive, we reuse a single instance many times.

This may bring other advantages, such as faster convergence when starting from the previous final state, and in some cases may be necessary if micromodel state needs to be preserved from one macro timestep to the next.

So in MUSCLE, submodels run in a reuse loop, which runs them over and over again until their work is done and they should be shut down. Whether to do another F_INIT, O_I, S, O_F cycle is decided by this method.

This method must be called at the beginning of the reuse loop, i.e. before the F_INIT operator, and its return value should decide whether to enter that loop again.

Raises:

RuntimeError – When implementing the checkpointing API, but libmuscle detected incorrect API calls. The description of the RuntimeError indicates which calls are incorrect or missing. For more information see the checkpointing API documentation in resuming(), load_snapshot(), should_save_snapshot(), save_snapshot(), should_save_final_snapshot() and save_final_snapshot(), or the checkpointing tutorial.

save_final_snapshot(message: Message) → None[source]

Save a snapshot at the end of the reuse loop.

Before saving a snapshot, you should check using should_save_final_snapshot() if a snapshot should be saved according to the checkpoint rules specified in the ymmsl configuration.

See also save_snapshot() for the variant that may be called after each S Operator of the submodel.

Parameters:

message – Message object that is saved as snapshot. The data attribute can be used to store the internal state of the submodel.

save_snapshot(message: Message) → None[source]

Save a snapshot after the S Operator of the submodel.

Before saving a snapshot, you should check using should_save_snapshot() if a snapshot should be saved according to the checkpoint rules specified in the ymmsl configuration. You should use the same timestamp in the provided Message object as used to query should_save_snapshot.

See also save_final_snapshot() for the variant that must be called at the end of the reuse loop.

Parameters:

message – Message object that is saved as snapshot. The message timestamp attribute should be the same as passed to should_save_snapshot(). The data attribute can be used to store the internal state of the submodel.

send(port_name: str, message: Message, slot: int | None = None) → None[source]

Send a message to the outside world.

Sending is non-blocking, a copy of the message will be made and stored in memory until the receiver is ready to receive it.

Parameters:

  • port_name – The port on which this message is to be sent.

  • message – The message to be sent.

  • slot – The slot to send the message on, if any.

set_port_length(port: str, length: int) → None[source]

Resizes the port to the given length.

You should check whether the port is resizable using is_resizable() first; whether it is depends on how this component is wired up, so you should check.

Parameters:

  • port – Name of the port to resize.

  • length – The new length.

Raises:

RuntimeError – If the port is not resizable.

should_init() → bool[source]

Check if this instance should initialize.

Must be used by submodels that implement the checkpointing API.

When resuming from a previous snapshot, instances need not always execute the F_INIT phase of the submodel execution loop. Use this method before attempting to receive data on F_INIT ports.

Returns:

True if the submodel must execute the F_INIT step, False otherwise.

should_save_final_snapshot() → bool[source]

Check if a snapshot should be saved at the end of the reuse loop.

This method checks if a snapshot should be saved at the end of the reuse loop. All your communication on O_F ports must be finished before calling this method, otherwise your simulation may deadlock.

When this method returns True, the submodel must also save a snapshot through save_final_snapshot(). A RuntimeError will be generated if this is not done.

See also should_save_snapshot() for the variant that may be called inside of a time-integration loop of the submodel.

Note

This method will block until it can determine whether a final snapshot should be taken, because it must determine if this instance is reused.

Returns:

True iff a final snapshot should be taken by the submodel according to the checkpoint rules provided in the ymmsl configuration.

should_save_snapshot(timestamp: float) → bool[source]

Check if a snapshot should be saved after the S Operator of the submodel.

This method checks if a snapshot should be saved right now, based on the provided timestamp and passed wallclock time.

When this method returns True, the submodel must also save a snapshot through save_snapshot(). A RuntimeError will be generated if this is not done.

See also should_save_final_snapshot() for the variant that must be called at the end of the reuse loop.

Parameters:

timestamp – current timestamp of the submodel.

Returns:

True iff a snapshot should be taken by the submodel according to the checkpoint rules provided in the ymmsl configuration.

class libmuscle.instance.InstanceFlags(value)[source]

Bases: Flag

Enumeration of properties that an instance may have.

You may combine multiple flags using the bitwise OR operator |. For example:

from libmuscle import (
        Instance, USES_CHECKPOINT_API, DONT_APPLY_OVERLAY)

ports = ...
flags = USES_CHECKPOINT_API | DONT_APPLY_OVERLAY
instance = Instance(ports, flags)
DONT_APPLY_OVERLAY = 1

Do not apply the received settings overlay during prereceive of F_INIT messages. If you’re going to use Instance.receive_with_settings() on your F_INIT ports, you need to set this flag when creating an Instance.

If you don’t know what that means, do not specify this flag and everything will be fine. If it turns out that you did need to specify the flag, MUSCLE3 will tell you about it in an error message and you can add it still.

KEEPS_NO_STATE_FOR_NEXT_USE = 4

Indicate this instance does not carry state between iterations of the reuse loop. Specifying this flag is equivalent to ymmsl.KeepsStateForNextUse.NO.

By default, (if neither KEEPS_NO_STATE_FOR_NEXT_USE nor STATE_NOT_REQUIRED_FOR_NEXT_USE are provided), the instance is assumed to keep state between reuses, and to require that state (equivalent to ymmsl.KeepsStateForNextUse.NECESSARY).

STATE_NOT_REQUIRED_FOR_NEXT_USE = 8

Indicate this instance carries state between iterations of the reuse loop, however this state is not required for restarting. Specifying this flag is equivalent to ymmsl.KeepsStateForNextUse.HELPFUL.

By default, (if neither KEEPS_NO_STATE_FOR_NEXT_USE nor STATE_NOT_REQUIRED_FOR_NEXT_USE are provided), the instance is assumed to keep state between reuses, and to require that state (equivalent to ymmsl.KeepsStateForNextUse.NECESSARY).

USES_CHECKPOINT_API = 2

Indicate that this instance supports checkpointing.

You may not use any checkpointing API calls when this flag is not supplied.