3.1.19. c3po.PhysicsDriver module

Inheritance diagram of c3po.PhysicsDriver

Contain the class PhysicsDriver.

class c3po.PhysicsDriver.PhysicsDriver

Bases: DataAccessor

PhysicsDriver is an abstract class which standardizes the functionalities expected by computer codes.

It follows the ICoCo (Interface for Code Coupling) V2 standard. The ICoCo V2 I/O (in/out) methods are defined in the mother class DataAccessor.

ICoCo V2 is originally defined for C++ here: https://github.com/cea-trust-platform/icoco-coupling. PhysicsDriver (together with DataAccessor) can be seen as the translation in Python of ICoCo V2.

In order to use a code with C3PO it is necessary to define a class that inherits from PhysicsDriver and to overload needed methods (including the ones of DataAccessor). Note that not all the methods need to be implemented! Mandatory methods are marked as such.

Some of the methods may not be called when some conditions are not met (i.e. when not in the correct context). Thus in this documentation we define the “TIME_STEP_DEFINED context” as the context that the code finds itself, when the method initTimeStep() has been called, and the method validateTimeStep() (or abortTimeStep()) has not yet been called. This is the status in which the current computation time step is well defined.

Within the computation of a time step (so within TIME_STEP_DEFINED), the temporal semantic of the fields (and scalar values) is not imposed by the norm. Said differently, it does not require the fields to be defined at the start/middle/end of the current time step, this semantic must be agreed on between the codes being coupled. Fields and scalar values that are set within the TIME_STEP_DEFINED context are invalidated (undefined behavior) after a call to validateTimeStep() (or abortTimeStep()). They need to be set at each time step. However, fields and scalar values that are set outside of this context (before the first time step for example, or after the resolution of the last time step) are permanent (unless modified afterward within the TIME_STEP_DEFINED context).

static GetICoCoMajorVersion()

(Mandatory) Return ICoCo interface major version number.

Returns:

ICoCo interface major version number (2 at present)

Return type:

int

__init__()

Default constructor.

Internal set up and initialization of the code should not be done here, but rather in initialize().

abortTimeStep()

(Optional) Abort the computation on the current time step.

Can be called whenever the computation time step is defined, instead of validateTimeStep(). After this call, the present time is left unchanged, and the computation time step is undefined (the code leaves the TIME_STEP_DEFINED context).

Raises:

AssertionError – If called outside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

computeTimeStep()

(Mandatory) Return the next preferred time step (time increment) for this code, and whether the code wants to stop.

Both data are only indicative, the supervisor is not required to take them into account. This method is however marked as mandatory, since most of the coupling schemes expect the code to provide this information (those schemes then typically compute the minimum of the time steps of all the codes being coupled). Hence a possible implementation is to return a huge value, if a precise figure can not be computed.

Can be called whenever the code is outside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

Returns:

A tuple (dt, stop). dt is the preferred time step for this code (only valid if stop is False). stop is True if the code wants to stop. It can be used for example to indicate that, according to a certain criterion, the end of the transient computation is reached from the code point of view.

Return type:

tuple(float, bool)

Raises:
forget(label, method)

(Optional) Discard a previously saved state of the code.

After this call, the save-point cannot be restored anymore. This method can be used to free the space occupied by unused saved states.

Parameters:

  • label (int) – A user- (or code-) defined value identifying the state.

  • method (str) – A string specifying which method was used to save the state of the code. A code can provide different methods (for example in memory, on disk, etc.).

Raises:
getInitNb()

Return the number of times init() has been called but not term().

This method is made to work with the wrappers init() and term(). It indicates the number of term() that are still needed to trigger terminate().

Returns:

The number of times init() has been called but not term().

Return type:

int

getInitStatus()

Return the output status of the last call to initialize() made through init().

Warning

This method, in association with init(), should always be used inside C3PO instead of initialize() which is not adapted to MPI Master-Workers paradigm.

This method should never be redefined: define initialize() instead!

Returns:

True if all OK, otherwise False.

Return type:

bool

getIterateStatus()

Return the output of the last call to iterateTimeStep() made through iterate().

Warning

This method, in association with iterate(), should always be used inside C3PO instead of iterateTimeStep(). They fit better with MPI use.

This method should never be redefined: define iterateTimeStep() instead!

Returns:

A tuple (succeed, converged). succeed = False if the computation fails. converged = True if the solution is not evolving any more.

Return type:

tuple(bool,bool)

getMEDCouplingMajorVersion()

(Optional) Get MEDCoupling major version, if the code was built with MEDCoupling support.

Mandatory if the code is built with MEDCoupling support. This can be used to assess compatibility between codes when coupling them.

Returns:

The MEDCoupling major version number (typically 7, 8, 9, …).

Return type:

int

getMPIComm()

(Optional) Return the MPI communicator used by the code for parallel computations.

Returns:

mpi4py communicator.

Return type:

mpi4py.MPI.Comm

getSolveStatus()

Return the output of the last call to solveTimeStep() made through solve().

Warning

This method, in association with solve(), should always be used inside C3PO instead of solveTimeStep(). They fit better with MPI use.

This method should never be redefined: define solveTimeStep() instead!

Returns:

True if computation was successful, False otherwise.

Return type:

bool

getStationaryMode()

(Mandatory) Indicate whether the code should compute a stationary solution or a transient one.

See also setStationaryMode().

Can be called whenever the code is outside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

Returns:

True if the code has been set to compute a stationary solution.

Return type:

bool

Raises:
init()

This is a recommanded wrapper for initialize().

It works with term() in order to guarantee that initialize() and terminate() are called only once:

init() also stores the return value of initialize() instead of returning it. The output is accessible with getInitStatus().

Warning

This method, in association with getInitStatus(), should always be used inside C3PO instead of initialize() which is not adapted to MPI Master-Workers paradigm.

Warning

This method should never be redefined: define initialize() instead!

initTimeStep(dt)

(Mandatory) Provide the next time step (time increment) to be used by the code.

After this call (if successful), the computation time step is defined to ]t, t + dt] where t is the value returned by presentTime(). The code enters the TIME_STEP_DEFINED context. A time step = 0. may be used when the stationaryMode is set to True for codes solving directly for the steady-state.

Parameters:

dt (float) – The time step to be used by the code.

Returns:

False means that the given time step is not compatible with the code time scheme.

Return type:

bool

Raises:
initialize()

(Mandatory) Initialize the current problem instance.

In this method the code should allocate all its internal structures and be ready to execute. File reads, memory allocations, and other operations likely to fail should be performed here, and not in the constructor (and not in the setDataFile() or in the setMPIComm() methods either). This method must be called only once (after a potential call to setMPIComm() and/or setDataFile()) and cannot be called again before terminate() has been performed.

Warning

This method is not adapted to MPI Master-Workers paradigm. init() and getInitStatus() methods should be used in C3PO instead.

Returns:

True if all OK, otherwise False.

Return type:

bool

Raises:

AssertionError – If called multiple times.

isMEDCoupling64Bits()

(Optional) Indicate whether the code was built with a 64-bits version of MEDCoupling.

Mandatory if the code is built with MEDCoupling support. This can be used to assess compatibility between codes when coupling them.

Returns:

True if the code was built with a 64-bits version of MEDCoupling.

Return type:

bool

isStationary()

(Optional) Return whether the solution is constant on the computation time step.

Used to know if the steady-state has been reached. This method can be called whenever the computation time step is not defined.

Returns:

True if the solution is constant on the computation time step.

Return type:

bool

Raises:
iterate()

Call iterateTimeStep() but store its return value instead of returning it.

The output is accessible with getIterateStatus().

Warning

This method, in association with getIterateStatus(), should always be used inside C3PO instead of iterateTimeStep(). They fit better with MPI use.

This method should never be redefined: define iterateTimeStep() instead!

iterateTimeStep()

(Optional) Perform a single iteration of computation inside the time step.

This method is relevant for codes having inner iterations for the computation of a single time step. Calling iterateTimeStep() until converged is True is equivalent to calling solveTimeStep(), within the code’s convergence threshold. Can be called (potentially several times) inside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

Warning

This method is not adapted to MPI Master-Workers paradigm. iterate() and getIterateStatus() methods should be used with C3PO instead.

Returns:

A tuple (succeed, converged). succeed = False if the computation fails. converged = True if the solution is not evolving any more.

Return type:

tuple(bool, bool)

Raises:

AssertionError – If called outside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

presentTime()

(Mandatory) Return the current time of the simulation.

Can be called any time between initialize() and terminate(). The current time can only change during a call to validateTimeStep() or to resetTime().

Returns:

The current (physical) time of the simulation.

Return type:

float

Raises:

AssertionError – If called before initialize() or after terminate().

resetTime(time_)

(Optional) Reset the current time of the PhysicsDriver to a given value.

New in version 2 of ICoCo. Particularly useful for the initialization of complex transients: the starting point of the transient of interest is computed first, the time is reset to 0, and then the actual transient of interest starts with proper initial conditions, and global time 0.

Can be called outside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

Parameters:

time_ (float) – The new current time.

Raises:
restore(label, method)

(Optional) Restore the state of the code.

After restore, the code should behave exactly like after the corresponding call to save (except of course for save/restore methods, since the list of saved states may have changed). The state to be restored is identified by the combination of label and method arguments. The save() method must have been called at some point or in some previous run with this combination.

Parameters:

  • label (int) – A user- (or code-) defined value identifying the state.

  • method (str) – A string specifying which method was used to save the state of the code. A code can provide different methods (for example in memory, on disk, etc.).

Raises:
save(label, method)

(Optional) Save the state of the code.

The saved state is identified by the combination of label and method arguments. If save() has already been called with the same two arguments, the saved state is overwritten.

Parameters:

  • label (int) – A user- (or code-) defined value identifying the state.

  • method (str) – A string specifying which method is used to save the state of the code. A code can provide different methods (for example in memory, on disk, etc.).

Raises:
setDataFile(datafile)

(Optional) Provide the relative path of a data file to be used by the code.

This method must be called before initialize().

Parameters:

datafile (str) – Relative path to the data file.

Raises:
setMPIComm(mpicomm)

(Optional) Provide the MPI communicator to be used by the code for parallel computations.

This method must be called before initialize(). The communicator should include all the processes to be used by the code. For a sequential code, the call to setMPIComm() is optional or mpicomm should be None.

Parameters:

mpicomm (mpi4py.MPI.Comm) – mpi4py communicator.

Raises:

AssertionError – If called multiple times or after initialize().

setStationaryMode(stationaryMode)

(Mandatory) Set whether the code should compute a stationary solution or a transient one.

New in version 2 of ICoCo. By default the code is assumed to be in stationary mode False (i.e. set up for a transient computation). If set to True, solveTimeStep() can be used either to solve a time step in view of an asymptotic solution, or to solve directly for the steady-state. In this last case, a time step = 0. can be used with initTimeStep() (whose call is always needed). The stationary mode status of the code can only be modified by this method (or by a call to terminate() followed by initialize()).

Can be called whenever the code is outside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

Parameters:

stationaryMode (bool) – True if the code should compute a stationary solution.

Raises:
setTransientLogger(transientLogger)

Defines the logger for solveTransient() method.

Parameters:

transientLogger (c3po.services.TransientLogger.TransientLogger) – Logger instance.

setTransientPrintLevel(level)

Set the print level for solveTransient() method (0=None, 1 keeps only the first and last lines, 2 keeps everything).

Parameters:

level (int) – Integer in range [0;2]. Default = 0.

solve()

Call solveTimeStep() but store its return value instead of returning it.

The output is accessible with getSolveStatus().

Warning

This method, in association with getSolveStatus(), should always be used inside C3PO instead of solveTimeStep(). They fit better with MPI use.

This method should never be redefined: define solveTimeStep() instead!

solveTimeStep()

(Mandatory) Perform the computation on the current time interval.

Can be called whenever the code is inside the TIME_STEP_DEFINED context (see PhysicsDriver documentation).

Warning

This method is not adapted to MPI Master-Workers paradigm. solve() and getSolveStatus() methods should be used with C3PO instead.

Returns:

True if computation was successful, False otherwise.

Return type:

bool

Raises:
solveTransient(tmax, finishAtTmax=False, stopIfStationary=False)

Make the PhysicsDriver to advance in time until it reaches the time tmax or it asks to stop.

The PhysicsDriver can ask to stop either with computeTimeStep() (always checked) or with isStationary() (only if stopIfStationary is set to True).

Parameters:

  • tmax (float) – Maximum time to be reached (compared with presentTime()).

  • finishAtTmax (bool) – If set to True, the method ends with time = tmax (instead of time >= tmax).

  • stopIfStationary (bool) – If set to True, the method stops also if isStationary() returns True.

term()

This is a recommanded wrapper for terminate().

It works with init() in order to guarantee that initialize() and terminate() are called only once:

Warning

This method should be used inside C3PO instead of terminate().

This method should never be redefined: define terminate() instead!

terminate()

(Mandatory) Terminate the current problem instance and release all allocated resources.

Terminate the computation, free the memory and save whatever needs to be saved. This method is called once at the end of the computation or after a non-recoverable error. No other ICoCo method except setDataFile(), setMPIComm() and initialize() may be called after this.

Raises:
validateTimeStep()

(Mandatory) Validate the computation performed by solveTimeStep().

Can be called whenever the code is inside the TIME_STEP_DEFINED context (see PhysicsDriver documentation). After this call:

  • the present time has been advanced to the end of the computation time step

  • the computation time step is undefined (the code leaves the TIME_STEP_DEFINED context).

Raises: