3.1.6.7. c3po.physicsDrivers.ICOCODriver module

Inheritance diagram of c3po.physicsDrivers.ICOCODriver

Contain the class ICOCODriver.

class c3po.physicsDrivers.ICOCODriver.ICOCODriver(problem)

Bases: PhysicsDriver

This is the implementation of PhysicsDriver for any ICoCo Problem implementation.

__init__(problem)

Build a ICOCODriver object.

Parameters:

problem – Implementation of the ICoCo Problem.

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:
getFieldType(name)

(Optional) Get the type of a field managed by the code.

(New in version 2) The three possible types are ‘Double’, ‘Int’ and ‘String’, as defined by ValueType.

Parameters:

name (str) – Field name.

Returns:

‘Double’, ‘Int’ or ‘String’, as defined by ValueType.

Return type:

str

Raises:
getFieldUnit(name)

(Optional) Get the physical unit used for a given field.

(New in version 2)

Parameters:

name (str) – Field name.

Returns:

Unit in which the field values should be understood (e.g. ‘W’, ‘J’, ‘Pa’, …).

Return type:

str

Raises:
getInputFieldsNames()

(Optional) Get the list of input fields accepted by the code.

Returns:

The list of field names that represent inputs of the code.

Return type:

list

Raises:

AssertionError – If implemented in a PhysicsDriver and called before initialize() or after terminate().

getInputMEDDoubleFieldTemplate(name)

(Optional) Retrieve an empty shell for an input field.

This shell can be filled by the caller and then be given to the code via setInputMEDDoubleField().

The code returns a field with all the data that represents the context of the field (i.e. its support mesh, its discretization – on nodes, on elements, …). The remaining job for the caller of this method is to fill the actual values of the field itself. When this is done the field can be sent back to the code through the method setInputMEDDoubleField(). This method is not mandatory but is useful to know the mesh, discretization… on which an input field is expected. Is is required by C3PO remapping functionalities.

See PhysicsDriver documentation for more details on the time semantic of a field.

Parameters:

name (str) – Name of the field for which we would like the empty shell.

Returns:

Field with all the contextual information.

Return type:

medcoupling.MEDCouplingFieldDouble

Raises:
getInputValuesNames()

(Optional) Get the list of input scalars accepted by the code.

Returns:

The list of scalar names that represent inputs of the code.

Return type:

list

Raises:

AssertionError – If implemented in a PhysicsDriver and called before initialize() or after terminate().

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

getMeshUnit()

(Optional) Get the (length) unit used to define the meshes supporting the fields.

(New in version 2)

Returns:

Length unit in which the mesh coordinates should be understood (e.g. ‘m’, ‘cm’, …).

Return type:

str

Raises:

AssertionError – If implemented in a PhysicsDriver and called before initialize() or after terminate().

getOutputDoubleValue(name)

(Optional) Retrieve a scalar float value from the code.

See PhysicsDriver documentation for more details on the time semantic of a scalar value.

Parameters:

name (str) – Name of the scalar value to be read from the code.

Returns:

The value read from the code.

Return type:

float

Raises:
getOutputFieldsNames()

(Optional) Get the list of output fields that can be provided by the code.

Returns:

The list of field names that can be produced by the code.

Return type:

list

Raises:

AssertionError – If implemented in a PhysicsDriver and called before initialize() or after terminate().

getOutputIntValue(name)

(Optional) Similar to getOutputDoubleValue() but for an int value.

getOutputMEDDoubleField(name)

(Optional) Return output data from the code in the form of a MEDCouplingFieldDouble.

See PhysicsDriver documentation for more details on the time semantic of a field.

Parameters:

name (str) – Name of the field that the caller requests from the code.

Returns:

Field with the data read by the code. The name and time properties of the field should be set in accordance with the ‘name’ parameter and with the current time step being computed.

Return type:

medcoupling.MEDCouplingFieldDouble

Raises:
getOutputStringValue(name)

(Optional) Similar to getOutputDoubleValue() but for an str value.

getOutputValuesNames()

(Optional) Get the list of output scalars that can be provided by the code.

Returns:

The list of scalar names that can be returned by the code.

Return type:

list

Raises:

AssertionError – If implemented in a PhysicsDriver and called before initialize() or after terminate().

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:
getValueType(name)

(Optional) Get the type of a scalar managed by the code.

(New in version 2) The three possible types are ‘Double’, ‘Int’ and ‘String’, as defined by ValueType.

Parameters:

name (str) – Scalar value name.

Returns:

‘Double’, ‘Int’ or ‘String’, as defined by ValueType.

Return type:

str

Raises:
getValueUnit(name)

(Optional) Get the physical unit used for a given value.

(New in version 2)

Parameters:

name (str) – Scalar value name.

Returns:

Unit in which the scalar value should be understood (e.g. ‘W’, ‘J’, ‘Pa’, …).

Return type:

str

Raises:
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:
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:
setInputDoubleValue(name, value)

(Optional) Provide the code with a scalar float data.

See PhysicsDriver documentation for more details on the time semantic of a scalar value.

Parameters:

  • name (str) – Name of the scalar value that is given to the code.

  • value (float) – Value passed to the code.

Raises:
setInputIntValue(name, value)

(Optional) Similar to setInputDoubleValue() but for an int value.

setInputMEDDoubleField(name, field)

(Optional) Provide the code with input data in the form of a MEDCouplingFieldDouble.

The method getInputMEDDoubleFieldTemplate(), if implemented, may be used first to prepare an empty shell of the field to pass to the code.

See PhysicsDriver documentation for more details on the time semantic of a field.

Parameters:

  • name (str) – Name of the field that is given to the code.

  • field (medcoupling.MEDCouplingFieldDouble) – Field containing the input data to be read by the code. The name of the field set on this instance (with the Field::setName method) should not be checked. However its time value should be to ensure it is within the proper time interval ]t, t+dt].

Raises:
setInputStringValue(name, value)

(Optional) Similar to setInputDoubleValue() but for an str value.

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:
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:
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:
updateOutputMEDDoubleField(name, field)

(Optional) Update a previously retrieved output field.

(New in version 2) This method allows the code to implement a more efficient update of a given output field, thus avoiding the caller to invoke getOutputMEDDoubleField() each time. A previous call to getOutputMEDDoubleField() with the same name must have been done prior to this call. The code should check the consistency of the field object with the requested data (same support mesh, discretization – on nodes, on elements, etc.).

See PhysicsDriver documentation for more details on the time semantic of a field.

Parameters:

  • name (str) – Name of the field that the caller requests from the code.

  • field (medcoupling.MEDCouplingFieldDouble) – Object updated with the data read from the code. Notably the time indicated in the field should be updated to be within the current time step being computed.

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: