Molssi Driver Interface Library: /repo/build/MDI_Library/MDI_Library/mdi.c File Reference

|  | Molssi Driver Interface Library

Functions | Variables
mdi.c File Reference

Functions callable by users of the MolSSI Driver Interface. More...

`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <errno.h>`
`#include "mdi.h"`
`#include "mdi_global.h"`
`#include "mdi_general.h"`
`#include "mdi_mpi.h"`
`#include "mdi_lib.h"`
`#include "physconst.h"`
`#include "elements.h"`

## Functions
int | MDI_Init (int *argc, char ***argv)
| Initialize communication through the MDI library. More...
int | MDI_Init_with_argv (int *argc, char ***argv)
| Initialize communication through the MDI library. More...
int | MDI_Init_code ()
| Initialize a code structure for the MDI library. More...
int | MDI_Init_with_options (const char *options)
| Initialize communication through the MDI library. More...
int | MDI_Initialized (int *flag)
| Indicates whether MDI_Init has been called. More...
int | MDI_Accept_Communicator (MDI_Comm *comm)
| Accept a new MDI communicator. More...
int | MDI_Accept_communicator (MDI_Comm *comm)
| Accept a new MDI communicator. More...
int | MDI_Send (const void *buf, int count, MDI_Datatype datatype, MDI_Comm comm)
| Send data through the MDI connection. More...
int | MDI_Recv (void *buf, int count, MDI_Datatype datatype, MDI_Comm comm)
| Receive data through the MDI connection. More...
int | MDI_Send_Command (const char *buf, MDI_Comm comm)
| Send a command of length `MDI_COMMAND_LENGTH` through the MDI connection. More...
int | MDI_Send_command (const char *buf, MDI_Comm comm)
| Send a command of length `MDI_COMMAND_LENGTH` through the MDI connection. More...
int | MDI_Recv_Command (char *buf, MDI_Comm comm)
| Receive a command of length `MDI_COMMAND_LENGTH` through the MDI connection. More...
int | MDI_Recv_command (char *buf, MDI_Comm comm)
| Receive a command of length `MDI_COMMAND_LENGTH` through the MDI connection. More...
int | MDI_Conversion_Factor (const char *in_unit, const char *out_unit, double *conv)
| Determine the conversion factor between two units. More...
int | MDI_Conversion_factor (const char *in_unit, const char *out_unit, double *conv)
| Determine the conversion factor between two units. More...
int | MDI_String_to_atomic_number (const char *element_symbol, int *atomic_number)
int | MDI_Get_Role (int *role)
| Get the role of the code. More...
int | MDI_Get_role (int *role)
| Get the role of the code. More...
int | MDI_Get_method (int *method, MDI_Comm comm)
| Get the communication method of a communicator. More...
int | MDI_Get_communicator (MDI_Comm *comm, int index)
| Get the previously accepted MDI communicator at a specific index in the array of all communicators. More...
void | MDI_Set_World_Size (int world_size_in)
| Set the size of MPI_COMM_WORLD. More...
void | MDI_Set_World_Rank (int world_rank_in)
| Set the rank of this process within MPI_COMM_WORLD. More...
int | MDI_Get_intra_rank (int intra_rank_out)
| Get the rank of this process within the MPI intra-communicator for the current code. More...
int | MDI_Register_Node (const char *node_name)
| Register a node. More...
int | MDI_Register_node (const char *node_name)
| Register a node. More...
int | MDI_Check_Node_Exists (const char *node_name, MDI_Comm comm, int *flag)
| Check whether a node is supported on a specified engine. More...
int | MDI_Check_node_exists (const char *node_name, MDI_Comm comm, int *flag)
| Check whether a node is supported on a specified engine. More...
int | MDI_Get_NNodes (MDI_Comm comm, int *nnodes)
| Get the number of nodes on a specified engine. More...
int | MDI_Get_nnodes (MDI_Comm comm, int *nnodes)
| Get the number of nodes on a specified engine. More...
int | MDI_Get_Node (int index, MDI_Comm comm, char *name)
| Get the name of a node on a specified engine. More...
int | MDI_Get_node (int index, MDI_Comm comm, char *name)
| Get the name of a node on a specified engine. More...
int | MDI_Register_Command (const char *node_name, const char *command_name)
| Register a command on a specified node. More...
int | MDI_Register_command (const char *node_name, const char *command_name)
| Register a command on a specified node. More...
int | MDI_Check_Command_Exists (const char *node_name, const char *command_name, MDI_Comm comm, int *flag)
| Check whether a command is supported on specified node on a specified engine. More...
int | MDI_Check_command_exists (const char *node_name, const char *command_name, MDI_Comm comm, int *flag)
| Check whether a command is supported on specified node on a specified engine. More...
int | MDI_Get_NCommands (const char *node_name, MDI_Comm comm, int *ncommands)
| Get the number of commands supported for a specified node on a specified engine. More...
int | MDI_Get_ncommands (const char *node_name, MDI_Comm comm, int *ncommands)
| Get the number of commands supported for a specified node on a specified engine. More...
int | MDI_Get_Command (const char *node_name, int index, MDI_Comm comm, char *name)
| Get the name of a command on a specified node on a specified engine. More...
int | MDI_Get_command (const char *node_name, int index, MDI_Comm comm, char *name)
| Get the name of a command on a specified node on a specified engine. More...
int | MDI_Register_Callback (const char *node_name, const char *callback_name)
| Register a callback on a specified node. More...
int | MDI_Register_callback (const char *node_name, const char *callback_name)
| Register a callback on a specified node. More...
int | MDI_Check_Callback_Exists (const char *node_name, const char *callback_name, MDI_Comm comm, int *flag)
| Check whether a callback exists on specified node on a specified engine. More...
int | MDI_Check_callback_exists (const char *node_name, const char *callback_name, MDI_Comm comm, int *flag)
| Check whether a callback exists on specified node on a specified engine. More...
int | MDI_Get_NCallbacks (const char *node_name, MDI_Comm comm, int *ncallbacks)
| Get the number of callbacks on a specified node on a specified engine. More...
int | MDI_Get_ncallbacks (const char *node_name, MDI_Comm comm, int *ncallbacks)
| Get the number of callbacks on a specified node on a specified engine. More...
int | MDI_Get_Callback (const char *node_name, int index, MDI_Comm comm, char *name)
| Get the name of a callback on a specified node on a specified engine. More...
int | MDI_Get_callback (const char *node_name, int index, MDI_Comm comm, char *name)
| Get the name of a callback on a specified node on a specified engine. More...
int | MDI_MPI_get_world_comm (void *world_comm)
| Obtain the MPI communicator that spans the single code corresponding to the calling rank. More...
int | MDI_MPI_set_world_comm (void *world_comm)
| Set the MPI communicator that spans the single code corresponding to the calling rank. More...
int | MDI_Launch_plugin (const char *plugin_name, const char *options, void *mpi_comm_ptr, MDI_Driver_node_callback_t driver_node_callback, void *driver_callback_object)
| Launch an MDI plugin instance. More...
int | MDI_Open_plugin (const char *plugin_name, const char *options, void *mpi_comm_ptr, MDI_Comm *mdi_comm_ptr)
| Open an MDI plugin instance in the background. More...
int | MDI_Close_plugin (MDI_Comm mdi_comm)
| Close an MDI plugin instance. More...
int | MDI_Set_Execute_Command_Func (int(*generic_command)(const char *, MDI_Comm, void *), void *class_object)
| Set the callback MDI uses for MDI_Execute_Command. More...
int | MDI_Set_execute_command_func (int(*generic_command)(const char *, MDI_Comm, void *), void *class_object)
| Set the callback MDI uses for MDI_Execute_Command. More...
int | MDI_Set_plugin_state (void *state)
int | MDI_Set_plugin_state_internal (void *state)
| Set the language-based callback for when a code is destroyed. More...
int | MDI_Set_on_destroy_code (int(*func)(int))
| Set the language-based callback for when a code is destroyed. More...
int | MDI_Get_Current_Code ()
| Get the current code. More...
int | MDI_Plugin_get_argc (int *argc_ptr)
| Get plugin_argc. More...
int | MDI_Plugin_get_argv (char ***argv_ptr)
| Get plugin_argv. More...
int | MDI_Plugin_get_args (char **args_ptr)
| Get plugin_unedited_options. More...
int | MDI_Plugin_get_arg (int index, char **arg_ptr)
| Get a specific element from plugin_argv. More...
int | MDI_Get_python_plugin_mpi_world_ptr (void **python_plugin_mpi_world_ptr_ptr, void *state_in)
| Get the Python plugin MPI communicator. More...
int | MDI_Set_Mpi4py_Recv_Callback (int(*mpi4py_recv)(void *, int, int, int, MDI_Comm))
| Set the callback MDI uses for MPI_Recv when using mpi4py. More...
int | MDI_Set_Mpi4py_Send_Callback (int(*mpi4py_send)(void *, int, int, int, MDI_Comm))
| Set the callback MDI uses for MPI_Send when using mpi4py. More...
int | MDI_Set_Mpi4py_Allgather_Callback (int(*mpi4py_allgather)(void *, void *))
| Set the callback MDI uses for gathering MDI versions when using mpi4py. More...
int | MDI_Set_Mpi4py_Gather_Names_Callback (int(*mpi4py_gather_names)(void *, void *, int *, int *))
| Set the callback MDI uses for gathering code names when using mpi4py. More...
int | MDI_Set_Mpi4py_Split_Callback (int(*mpi4py_split)(int, int, MDI_Comm, int))
| Set the callback MDI uses for MPI_Split when using mpi4py. More...
int | MDI_Set_Mpi4py_Rank_Callback (int(*mpi4py_rank)(int))
| Set the callback MDI uses for MPI_Comm_rank when using mpi4py. More...
int | MDI_Set_Mpi4py_Size_Callback (int(*mpi4py_size)(int))
| Set the callback MDI uses for MPI_Comm_size when using mpi4py. More...
int | MDI_Set_Mpi4py_Barrier_Callback (int(*mpi4py_barrier)(int))
| Set the callback MDI uses for MPI_Barrier when using mpi4py. More...
int | MDI_Set_Launch_Plugin_Callback (int(*launch_plugin)(void *, void *, void *, int))
| Set the callback MDI uses for MDI_Plugin_init when the driver is in Python. More...
int | MDI_Set_plugin_language (int language, void *plugin_state)
| Set the language of an MDI plugin. More...
int | MDI_Set_language_execute_command (int(*execute_command)(void *, MDI_Comm, void *))
| Set the language execute_command function needed by a language wrapper. More...
MDI_Driver_node_callback_f90_t | MDI_Get_language_driver_callback ()
| Get the language driver callback needed by a language wrapper. More...
int | MDI_Set_language_driver_callback (MDI_Driver_node_callback_f90_t callback)
| Set the language-specific driver_callback function needed by a language wrapper. More...
int | MDI_Call_language_driver_callback (void *class_obj)
| Call the language driver callback needed by a language wrapper. More...

## Variables
const int | MDI_MAJOR_VERSION = MDI_MAJOR_VERSION_
| MDI major version number.
const int | MDI_MINOR_VERSION = MDI_MINOR_VERSION_
| MDI minor version number.
const int | MDI_PATCH_VERSION = MDI_PATCH_VERSION_
| MDI patch version number.
const int | MDI_COMMAND_LENGTH = MDI_COMMAND_LENGTH_
| length of an MDI command in characters
const int | MDI_NAME_LENGTH = MDI_NAME_LENGTH_
| length of an MDI name in characters
const int | MDI_LABEL_LENGTH = MDI_LABEL_LENGTH_
| length of an MDI label in characters
const MDI_Comm | MDI_COMM_NULL = MDI_COMM_NULL_
| value of a null communicator
const int | MDI_INT = MDI_INT_
| integer data type
const int | MDI_INT8_T = MDI_INT8_T_
| int8_t data type
const int | MDI_INT16_T = MDI_INT16_T_
| int16_t data type
const int | MDI_INT32_T = MDI_INT32_T_
| int32_t data type
const int | MDI_INT64_T = MDI_INT64_T_
| int64_t data type
const int | MDI_UINT8_T = MDI_UINT8_T_
| uint8_t data type
const int | MDI_UINT16_T = MDI_UINT16_T_
| uint16_t data type
const int | MDI_UINT32_T = MDI_UINT32_T_
| uint32_t data type
const int | MDI_UINT64_T = MDI_UINT64_T_
| uint64_t data type
const int | MDI_DOUBLE = MDI_DOUBLE_
| double precision float data type
const int | MDI_CHAR = MDI_CHAR_
| character data type
const int | MDI_FLOAT = MDI_FLOAT_
| single precision float data type
const int | MDI_BYTE = MDI_BYTE_
| character data type
const int | MDI_TCP = MDI_TCP_
| TCP/IP communication method.
const int | MDI_MPI = MDI_MPI_
| MPI communication method.
const int | MDI_LINK = MDI_LINK_
| Library communication method (deprecated)
const int | MDI_PLUGIN = MDI_LINK_
| Library communication method.
const int | MDI_TEST = MDI_TEST_
| Test communication method.
const int | MDI_DRIVER = MDI_DRIVER_
| Driver role type.
const int | MDI_ENGINE = MDI_ENGINE_
| Engine role type.
int(*)(void *, MDI_Comm, void *) | MDI_Get_language_execute_command (MDI_Comm comm)
| Get the language execute_command function needed by a language wrapper. More...

## Detailed Description

Functions callable by users of the MolSSI Driver Interface.

## Function Documentation

## ◆ MDI_Accept_Communicator()

int MDI_Accept_Communicator | ( | MDI_Comm * | comm | ) |

Accept a new MDI communicator.

The function returns an MDI_Comm that describes a connection between two codes. If no new communicators are available, the function returns `MDI_COMM_NULL`.

## ◆ MDI_Accept_communicator()

int MDI_Accept_communicator | ( | MDI_Comm * | comm | ) |

Accept a new MDI communicator.

The function returns an MDI_Comm that describes a connection between two codes. If no new communicators are available, the function returns `MDI_COMM_NULL`.

## ◆ MDI_Call_language_driver_callback()

int MDI_Call_language_driver_callback | ( | void * | class_obj | ) |

Call the language driver callback needed by a language wrapper.

The function returns a function pointer to the driver callback function.

Parameters

  [out] | callback | Driver callback
  [in] | comm | MDI communicator

## ◆ MDI_Check_Callback_Exists()

int MDI_Check_Callback_Exists | ( | const char * | node_name,
|  | const char * | callback_name,
|  | MDI_Comm | comm,
|  | int * | flag
| ) |  |

Check whether a callback exists on specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the callbacks's node.
  [in] | command_name | Name of the callback.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | flag | On return, 1 if the callback is supported and 0 otherwise.

## ◆ MDI_Check_callback_exists()

int MDI_Check_callback_exists | ( | const char * | node_name,
|  | const char * | callback_name,
|  | MDI_Comm | comm,
|  | int * | flag
| ) |  |

Check whether a callback exists on specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the callbacks's node.
  [in] | command_name | Name of the callback.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | flag | On return, 1 if the callback is supported and 0 otherwise.

## ◆ MDI_Check_Command_Exists()

int MDI_Check_Command_Exists | ( | const char * | node_name,
|  | const char * | command_name,
|  | MDI_Comm | comm,
|  | int * | flag
| ) |  |

Check whether a command is supported on specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the command's node.
  [in] | command_name | Name of the command.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | flag | On return, 1 if the command is supported and 0 otherwise.

## ◆ MDI_Check_command_exists()

int MDI_Check_command_exists | ( | const char * | node_name,
|  | const char * | command_name,
|  | MDI_Comm | comm,
|  | int * | flag
| ) |  |

Check whether a command is supported on specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the command's node.
  [in] | command_name | Name of the command.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | flag | On return, 1 if the command is supported and 0 otherwise.

## ◆ MDI_Check_Node_Exists()

int MDI_Check_Node_Exists | ( | const char * | node_name,
|  | MDI_Comm | comm,
|  | int * | flag
| ) |  |

Check whether a node is supported on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | flag | On return, 1 if the node is supported and 0 otherwise.

## ◆ MDI_Check_node_exists()

int MDI_Check_node_exists | ( | const char * | node_name,
|  | MDI_Comm | comm,
|  | int * | flag
| ) |  |

Check whether a node is supported on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | flag | On return, 1 if the node is supported and 0 otherwise.

## ◆ MDI_Close_plugin()

int MDI_Close_plugin | ( | MDI_Comm | mdi_comm | ) |

Close an MDI plugin instance.

The function returns `0` on a success.

Parameters

  [in] | plugin_name | Name of the plugin.
  [in] | options | Command-line options for the plugin.
  [in] | mpi_comm_ptr | Pointer to an MPI intra-communicator that spans all ranks that will run this plugin instance.
  [out] | mdi_comm_ptr | Pointer to an MDI communicator for communication with the launched plugin.

## ◆ MDI_Conversion_Factor()

int MDI_Conversion_Factor | ( | const char * | in_unit,
|  | const char * | out_unit,
|  | double * | conv
| ) |  |

Determine the conversion factor between two units.

The function determines the conversion factor from `in_unit` to `out_unit`. The function requires that `in_unit` and `out_unit` be members of the same category of unit (i.e. charge, energy, force, etc.). For example, calling `MDI_Conversion_Factor`(`"kilojoule_per_mol"`,`"atomic_unit_of_energy"`) will return the conversion factor from kilojoule/mol to hartrees. The function returns `0` on a success.

All quantities communicated through MDI must be represented using atomic units. When unit conversions are necessary, this function should be used to obtain the conversion factors, as this will ensure that all drivers and engines use conversion factors that are self-consistent across codes. Use of conversion factors that are not self-consistent can result in numerical instabilities.

The following is a list of the unit categories, along with the names of the units associated with each category:

- charge
  - atomic_unit_of_charge
  - coulomb
- energy
  - atomic_unit_of_energy
  - calorie
  - electron_volt
  - hartree
  - inverse_meter_energy
  - joule
  - kelvin_energy
  - kilocalorie
  - kilocalorie_per_mol
  - kilojoule
  - kilojoule_per_mol
  - rydberg
- force
  - atomic_unit_of_force
  - newton
- length
  - angstrom
  - atomic_unit_of_length
  - bohr
  - meter
  - nanometer
  - picometer
- mass
  - atomic_mass_unit
  - atomic_unit_of_mass
  - gram
  - kilogram
- time
  - atomic_unit_of_time
  - picosecond
  - second

All conversion factors were acquired from the NIST CODATA, except the conversion factors for calorie, kilocalorie, and kilocalorie_per_mol, which were obtained from the NIST Guide to the SI.

Parameters

  [in] | in_unit | Name of the unit to convert from.
  [in] | out_unit | Name of the unit to convert to.
  [out] | conv | Conversion factor from in_unit to out_unit

## ◆ MDI_Conversion_factor()

int MDI_Conversion_factor | ( | const char * | in_unit,
|  | const char * | out_unit,
|  | double * | conv
| ) |  |

Determine the conversion factor between two units.

The function determines the conversion factor from `in_unit` to `out_unit`. The function requires that `in_unit` and `out_unit` be members of the same category of unit (i.e. charge, energy, force, etc.). For example, calling `MDI_Conversion_Factor`(`"kilojoule_per_mol"`,`"atomic_unit_of_energy"`) will return the conversion factor from kilojoule/mol to hartrees. The function returns `0` on a success.

All quantities communicated through MDI must be represented using atomic units. When unit conversions are necessary, this function should be used to obtain the conversion factors, as this will ensure that all drivers and engines use conversion factors that are self-consistent across codes. Use of conversion factors that are not self-consistent can result in numerical instabilities.

The following is a list of the unit categories, along with the names of the units associated with each category:

- charge
  - atomic_unit_of_charge
  - coulomb
- energy
  - atomic_unit_of_energy
  - calorie
  - electron_volt
  - hartree
  - inverse_meter_energy
  - joule
  - kelvin_energy
  - kilocalorie
  - kilocalorie_per_mol
  - kilojoule
  - kilojoule_per_mol
  - rydberg
- force
  - atomic_unit_of_force
  - newton
- length
  - angstrom
  - atomic_unit_of_length
  - bohr
  - meter
  - nanometer
  - picometer
- mass
  - atomic_mass_unit
  - atomic_unit_of_mass
  - gram
  - kilogram
- time
  - atomic_unit_of_time
  - picosecond
  - second

All conversion factors were acquired from the NIST CODATA, except the conversion factors for calorie, kilocalorie, and kilocalorie_per_mol, which were obtained from the NIST Guide to the SI.

Parameters

  [in] | in_unit | Name of the unit to convert from.
  [in] | out_unit | Name of the unit to convert to.
  [out] | conv | Conversion factor from in_unit to out_unit

## ◆ MDI_Get_Callback()

int MDI_Get_Callback | ( | const char * | node_name,
|  | int | index,
|  | MDI_Comm | comm,
|  | char * | name
| ) |  |

Get the name of a callback on a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the callback is located.
  [in] | index | Index of the callback on the specified node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | name | On return, the name of the callback

## ◆ MDI_Get_callback()

int MDI_Get_callback | ( | const char * | node_name,
|  | int | index,
|  | MDI_Comm | comm,
|  | char * | name
| ) |  |

Get the name of a callback on a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the callback is located.
  [in] | index | Index of the callback on the specified node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | name | On return, the name of the callback

## ◆ MDI_Get_Command()

int MDI_Get_Command | ( | const char * | node_name,
|  | int | index,
|  | MDI_Comm | comm,
|  | char * | name
| ) |  |

Get the name of a command on a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the command is located.
  [in] | index | Index of the command on the specified node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | name | On return, the name of the command

## ◆ MDI_Get_command()

int MDI_Get_command | ( | const char * | node_name,
|  | int | index,
|  | MDI_Comm | comm,
|  | char * | name
| ) |  |

Get the name of a command on a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the command is located.
  [in] | index | Index of the command on the specified node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | name | On return, the name of the command

## ◆ MDI_Get_communicator()

int MDI_Get_communicator | ( | MDI_Comm * | comm,
|  | int | index
| ) |  |

Get the previously accepted MDI communicator at a specific index in the array of all communicators.

The function returns `0` on a success.

Parameters

  [out] | comm | Value of the communicator. If no communicator exists at the given index, returns `MDI_COMM_NULL`.
  [in] | index | Request the i'th communicator in the list of accepted and valid communicators. The list begins at `0`.

## ◆ MDI_Get_Current_Code()

int MDI_Get_Current_Code | ( |  | ) |

Get the current code.

## ◆ MDI_Get_intra_rank()

int MDI_Get_intra_rank | ( | int | intra_rank_out | ) |

Get the rank of this process within the MPI intra-communicator for the current code.

This function is only used by the Fortran wrapper

## ◆ MDI_Get_language_driver_callback()

MDI_Driver_node_callback_f90_t MDI_Get_language_driver_callback | ( |  | ) |

Get the language driver callback needed by a language wrapper.

The function returns a function pointer to the driver callback function.

Parameters

  [out] | callback | Driver callback
  [in] | comm | MDI communicator

## ◆ MDI_Get_method()

int MDI_Get_method | ( | int * | method,
|  | MDI_Comm | comm
| ) |  |

Get the communication method of a communicator.

The function returns `0` on a success.

Parameters

  [out] | method | Role of the code (either `MDI_TCP`, `MDI_MPI`, `MDI_TEST`, or `MDI_PLUGIN`)
  [in] | comm | MDI communicator for which the library will return the communication method.

## ◆ MDI_Get_NCallbacks()

int MDI_Get_NCallbacks | ( | const char * | node_name,
|  | MDI_Comm | comm,
|  | int * | ncallbacks
| ) |  |

Get the number of callbacks on a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | ncallbacks | On return, the number of callbacks on the specified node on the specified engine.

## ◆ MDI_Get_ncallbacks()

int MDI_Get_ncallbacks | ( | const char * | node_name,
|  | MDI_Comm | comm,
|  | int * | ncallbacks
| ) |  |

Get the number of callbacks on a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | ncallbacks | On return, the number of callbacks on the specified node on the specified engine.

## ◆ MDI_Get_NCommands()

int MDI_Get_NCommands | ( | const char * | node_name,
|  | MDI_Comm | comm,
|  | int * | ncommands
| ) |  |

Get the number of commands supported for a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | nnodes | On return, the number of commands supported on the specified engine on the specified node.

## ◆ MDI_Get_ncommands()

int MDI_Get_ncommands | ( | const char * | node_name,
|  | MDI_Comm | comm,
|  | int * | ncommands
| ) |  |

Get the number of commands supported for a specified node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | nnodes | On return, the number of commands supported on the specified engine on the specified node.

## ◆ MDI_Get_NNodes()

int MDI_Get_NNodes | ( | MDI_Comm | comm,
|  | int * | nnodes
| ) |  |

Get the number of nodes on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | nnodes | On return, the number of nodes supported by the engine.

## ◆ MDI_Get_nnodes()

int MDI_Get_nnodes | ( | MDI_Comm | comm,
|  | int * | nnodes
| ) |  |

Get the number of nodes on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | nnodes | On return, the number of nodes supported by the engine.

## ◆ MDI_Get_Node()

int MDI_Get_Node | ( | int | index,
|  | MDI_Comm | comm,
|  | char * | name
| ) |  |

Get the name of a node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | index | Index of the node on the specified engine.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | name | On return, the name of the node

## ◆ MDI_Get_node()

int MDI_Get_node | ( | int | index,
|  | MDI_Comm | comm,
|  | char * | name
| ) |  |

Get the name of a node on a specified engine.

The function returns `0` on a success.

Parameters

  [in] | index | Index of the node on the specified engine.
  [in] | comm | MDI communicator of the engine. If comm is set to MDI_COMM_NULL, the function will check for the calling engine.
  [out] | name | On return, the name of the node

## ◆ MDI_Get_python_plugin_mpi_world_ptr()

int MDI_Get_python_plugin_mpi_world_ptr | ( | void ** | python_plugin_mpi_world_ptr_ptr,
|  | void * | state_in
| ) |  |

Get the Python plugin MPI communicator.

## ◆ MDI_Get_Role()

int MDI_Get_Role | ( | int * | role | ) |

Get the role of the code.

The function returns `0` on a success.

Parameters

  [out] | role | Role of the code (either `MDI_DRIVER` or `MDI_ENGINE`)

## ◆ MDI_Get_role()

int MDI_Get_role | ( | int * | role | ) |

Get the role of the code.

The function returns `0` on a success.

Parameters

  [out] | role | Role of the code (either `MDI_DRIVER` or `MDI_ENGINE`)

## ◆ MDI_Init()

int MDI_Init | ( | int * | argc,
|  | char *** | argv
| ) |  |

Initialize communication through the MDI library.

If using the "-method MPI" option, this function must be called by all ranks. The function returns `0` on a success.

Parameters

  [in,out] | argc | Pointer to the number of arguments.
  [in,out] | argv | Pointer to the argument vector.

## ◆ MDI_Init_code()

int MDI_Init_code | ( |  | ) |

Initialize a code structure for the MDI library.

The function returns `0` on a success.

## ◆ MDI_Init_with_argv()

int MDI_Init_with_argv | ( | int * | argc,
|  | char *** | argv
| ) |  |

Initialize communication through the MDI library.

If using the "-method MPI" option, this function must be called by all ranks. The function returns `0` on a success.

Parameters

  [in,out] | argc | Pointer to the number of arguments.
  [in,out] | argv | Pointer to the argument vector.

## ◆ MDI_Init_with_options()

int MDI_Init_with_options | ( | const char * | options | ) |

Initialize communication through the MDI library.

If using the "-method MPI" option, this function must be called by all ranks. The function returns `0` on a success.

Parameters

  [in] | options | Options describing the communication method used to connect to codes.
  [in,out] | world_comm | On input, the MPI communicator that spans all of the codes. On output, the MPI communicator that spans the single code corresponding to the calling rank. Only used if the "-method MPI" option is provided.

## ◆ MDI_Initialized()

int MDI_Initialized | ( | int * | flag | ) |

Indicates whether MDI_Init has been called.

Parameters

  [out] | flag | Flag is true if and only if MDI_Init has been called.

## ◆ MDI_Launch_plugin()

int MDI_Launch_plugin | ( | const char * | plugin_name,
|  | const char * | options,
|  | void * | mpi_comm_ptr,
|  | MDI_Driver_node_callback_t | driver_node_callback,
|  | void * | driver_callback_object
| ) |  |

Launch an MDI plugin instance.

The function returns `0` on a success.

Parameters

  [in] | plugin_name | Name of the plugin.
  [in] | options | Command-line options for the plugin.
  [in] | mpi_comm_ptr | Pointer to an MPI intra-communicator that spans all ranks that will run this plugin instance.
  [in] | driver_node_callback | Function pointer to the driver code that will be executed on this engine.
  [in] | driver_callback_object | Pointer to the object instance of which driver_node_callback is a class member. Should be set void if driver_node_callback is not a member of a class.

## ◆ MDI_MPI_get_world_comm()

int MDI_MPI_get_world_comm | ( | void * | world_comm | ) |

Obtain the MPI communicator that spans the single code corresponding to the calling rank.

The function returns `0` on a success.

Parameters

  [out] | world_comm | On output, the MPI communicator that spans the single code corresponding to the calling rank.

## ◆ MDI_MPI_set_world_comm()

int MDI_MPI_set_world_comm | ( | void * | world_comm | ) |

Set the MPI communicator that spans the single code corresponding to the calling rank.

The function returns `0` on a success.

Parameters

  [out] | world_comm | The MPI communicator that spans the single code corresponding to the calling rank.

## ◆ MDI_Open_plugin()

int MDI_Open_plugin | ( | const char * | plugin_name,
|  | const char * | options,
|  | void * | mpi_comm_ptr,
|  | MDI_Comm * | mdi_comm_ptr
| ) |  |

Open an MDI plugin instance in the background.

The function returns `0` on a success.

Parameters

  [in] | plugin_name | Name of the plugin.
  [in] | options | Command-line options for the plugin.
  [in] | mpi_comm_ptr | Pointer to an MPI intra-communicator that spans all ranks that will run this plugin instance.
  [out] | mdi_comm_ptr | Pointer to an MDI communicator for communication with the launched plugin.

## ◆ MDI_Plugin_get_arg()

int MDI_Plugin_get_arg | ( | int | index,
|  | char ** | arg_ptr
| ) |  |

Get a specific element from plugin_argv.

## ◆ MDI_Plugin_get_argc()

int MDI_Plugin_get_argc | ( | int * | argc_ptr | ) |

Get plugin_argc.

## ◆ MDI_Plugin_get_args()

int MDI_Plugin_get_args | ( | char ** | args_ptr | ) |

Get plugin_unedited_options.

## ◆ MDI_Plugin_get_argv()

int MDI_Plugin_get_argv | ( | char *** | argv_ptr | ) |

Get plugin_argv.

## ◆ MDI_Recv()

int MDI_Recv | ( | void * | buf,
|  | int | count,
|  | MDI_Datatype | datatype,
|  | MDI_Comm | comm
| ) |  |

Receive data through the MDI connection.

If running with MPI, this function must be called only by rank `0`. The function returns `0` on a success.

Parameters

  [in] | buf | Pointer to the buffer where the received data will be stored.
  [in] | count | Number of values (integers, double precision floats, characters, etc.) to be received.
  [in] | datatype | MDI handle (MDI_INT, MDI_DOUBLE, MDI_CHAR, etc.) corresponding to the type of data to be received.
  [in] | comm | MDI communicator associated with the connection to the sending code.

## ◆ MDI_Recv_Command()

int MDI_Recv_Command | ( | char * | buf,
|  | MDI_Comm | comm
| ) |  |

Receive a command of length `MDI_COMMAND_LENGTH` through the MDI connection.

If running with MPI, this function must be called only by rank `0`. The function returns `0` on a success.

Parameters

  [in] | buf | Pointer to the buffer where the received data will be stored.
  [in] | comm | MDI communicator associated with the connection to the sending code.

## ◆ MDI_Recv_command()

int MDI_Recv_command | ( | char * | buf,
|  | MDI_Comm | comm
| ) |  |

Receive a command of length `MDI_COMMAND_LENGTH` through the MDI connection.

If running with MPI, this function must be called only by rank `0`. The function returns `0` on a success.

Parameters

  [in] | buf | Pointer to the buffer where the received data will be stored.
  [in] | comm | MDI communicator associated with the connection to the sending code.

## ◆ MDI_Register_Callback()

int MDI_Register_Callback | ( | const char * | node_name,
|  | const char * | callback_name
| ) |  |

Register a callback on a specified node.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the callback will be registered.
  [in] | callback_name | Name of the callback.

## ◆ MDI_Register_callback()

int MDI_Register_callback | ( | const char * | node_name,
|  | const char * | callback_name
| ) |  |

Register a callback on a specified node.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the callback will be registered.
  [in] | callback_name | Name of the callback.

## ◆ MDI_Register_Command()

int MDI_Register_Command | ( | const char * | node_name,
|  | const char * | command_name
| ) |  |

Register a command on a specified node.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the command will be registered.
  [in] | command_name | Name of the command.

## ◆ MDI_Register_command()

int MDI_Register_command | ( | const char * | node_name,
|  | const char * | command_name
| ) |  |

Register a command on a specified node.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node on which the command will be registered.
  [in] | command_name | Name of the command.

## ◆ MDI_Register_Node()

int MDI_Register_Node | ( | const char * | node_name | ) |

Register a node.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.

## ◆ MDI_Register_node()

int MDI_Register_node | ( | const char * | node_name | ) |

Register a node.

The function returns `0` on a success.

Parameters

  [in] | node_name | Name of the node.

## ◆ MDI_Send()

int MDI_Send | ( | const void * | buf,
|  | int | count,
|  | MDI_Datatype | datatype,
|  | MDI_Comm | comm
| ) |  |

Send data through the MDI connection.

If running with MPI, this function must be called only by rank `0`. The function returns `0` on a success.

Parameters

  [in] | buf | Pointer to the data to be sent.
  [in] | count | Number of values (integers, double precision floats, characters, etc.) to be sent.
  [in] | datatype | MDI handle (MDI_INT, MDI_DOUBLE, MDI_CHAR, etc.) corresponding to the type of data to be sent.
  [in] | comm | MDI communicator associated with the intended recipient code.

## ◆ MDI_Send_Command()

int MDI_Send_Command | ( | const char * | buf,
|  | MDI_Comm | comm
| ) |  |

Send a command of length `MDI_COMMAND_LENGTH` through the MDI connection.

If running with MPI, this function must be called only by rank `0`. The function returns `0` on a success.

Parameters

  [in] | buf | Pointer to the data to be sent.
  [in] | comm | MDI communicator associated with the intended recipient code.

## ◆ MDI_Send_command()

int MDI_Send_command | ( | const char * | buf,
|  | MDI_Comm | comm
| ) |  |

Send a command of length `MDI_COMMAND_LENGTH` through the MDI connection.

If running with MPI, this function must be called only by rank `0`. The function returns `0` on a success.

Parameters

  [in] | buf | Pointer to the data to be sent.
  [in] | comm | MDI communicator associated with the intended recipient code.

## ◆ MDI_Set_Execute_Command_Func()

int MDI_Set_Execute_Command_Func | ( | int(*)(const char *, MDI_Comm, void *) | generic_command,
|  | void * | class_object
| ) |  |

Set the callback MDI uses for MDI_Execute_Command.

The function returns `0` on a success.

Parameters

  [in] | execute_command | Function pointer to the generic execute_command function

## ◆ MDI_Set_execute_command_func()

int MDI_Set_execute_command_func | ( | int(*)(const char *, MDI_Comm, void *) | generic_command,
|  | void * | class_object
| ) |  |

Set the callback MDI uses for MDI_Execute_Command.

The function returns `0` on a success.

Parameters

  [in] | execute_command | Function pointer to the generic execute_command function

## ◆ MDI_Set_language_driver_callback()

int MDI_Set_language_driver_callback | ( | MDI_Driver_node_callback_f90_t | callback | ) |

Set the language-specific driver_callback function needed by a language wrapper.

The function returns `0` on a success.

Parameters

  [in] | callback | Driver callback

## ◆ MDI_Set_language_execute_command()

int MDI_Set_language_execute_command | ( | int(*)(void *, MDI_Comm, void *) | execute_command | ) |

Set the language execute_command function needed by a language wrapper.

The function returns `0` on a success.

Parameters

  [in] | execute_command | Execute command callback

## ◆ MDI_Set_Launch_Plugin_Callback()

int MDI_Set_Launch_Plugin_Callback | ( | int(*)(void *, void *, void *, int) | launch_plugin | ) |

Set the callback MDI uses for MDI_Plugin_init when the driver is in Python.

The function returns `0` on a success.

Parameters

  [in] | launch_plugin | Function pointer to the launch_plugin callback

## ◆ MDI_Set_Mpi4py_Allgather_Callback()

int MDI_Set_Mpi4py_Allgather_Callback | ( | int(*)(void *, void *) | mpi4py_allgather | ) |

Set the callback MDI uses for gathering MDI versions when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_allgather | Function pointer to the mpi4py_allgather callback

## ◆ MDI_Set_Mpi4py_Barrier_Callback()

int MDI_Set_Mpi4py_Barrier_Callback | ( | int(*)(int) | mpi4py_barrier | ) |

Set the callback MDI uses for MPI_Barrier when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_barrier | Function pointer to the mpi4py_barrier callback

## ◆ MDI_Set_Mpi4py_Gather_Names_Callback()

int MDI_Set_Mpi4py_Gather_Names_Callback | ( | int(*)(void *, void *, int *, int *) | mpi4py_gather_names | ) |

Set the callback MDI uses for gathering code names when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_gather_names | Function pointer to the mpi4py_gather_names callback

## ◆ MDI_Set_Mpi4py_Rank_Callback()

int MDI_Set_Mpi4py_Rank_Callback | ( | int(*)(int) | mpi4py_rank | ) |

Set the callback MDI uses for MPI_Comm_rank when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_rank | Function pointer to the mpi4py_rank callback

## ◆ MDI_Set_Mpi4py_Recv_Callback()

int MDI_Set_Mpi4py_Recv_Callback | ( | int(*)(void *, int, int, int, MDI_Comm) | mpi4py_recv | ) |

Set the callback MDI uses for MPI_Recv when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_recv | Function pointer to the mpi4py_recv callback

## ◆ MDI_Set_Mpi4py_Send_Callback()

int MDI_Set_Mpi4py_Send_Callback | ( | int(*)(void *, int, int, int, MDI_Comm) | mpi4py_send | ) |

Set the callback MDI uses for MPI_Send when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_send | Function pointer to the mpi4py_send callback

## ◆ MDI_Set_Mpi4py_Size_Callback()

int MDI_Set_Mpi4py_Size_Callback | ( | int(*)(int) | mpi4py_size | ) |

Set the callback MDI uses for MPI_Comm_size when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_size | Function pointer to the mpi4py_size callback

## ◆ MDI_Set_Mpi4py_Split_Callback()

int MDI_Set_Mpi4py_Split_Callback | ( | int(*)(int, int, MDI_Comm, int) | mpi4py_split | ) |

Set the callback MDI uses for MPI_Split when using mpi4py.

The function returns `0` on a success.

Parameters

  [in] | mpi4py_split | Function pointer to the mpi4py_split callback

## ◆ MDI_Set_on_destroy_code()

int MDI_Set_on_destroy_code | ( | int(*)(int) | func | ) |

Set the language-based callback for when a code is destroyed.

This is currently only used by Fortran plugins

## ◆ MDI_Set_plugin_language()

int MDI_Set_plugin_language | ( | int | language,
|  | void * | plugin_state
| ) |  |

Set the language of an MDI plugin.

The function returns `0` on a success.

Parameters

  [in] | language | Language of the plugin

## ◆ MDI_Set_plugin_state_internal()

int MDI_Set_plugin_state_internal | ( | void * | state | ) |

Set the language-based callback for when a code is destroyed.

This is only intended to be used internally by the MDI Library

## ◆ MDI_Set_World_Rank()

void MDI_Set_World_Rank | ( | int | world_rank_in | ) |

Set the rank of this process within MPI_COMM_WORLD.

This function is only used if the linked program uses MPI4PY.

## ◆ MDI_Set_World_Size()

void MDI_Set_World_Size | ( | int | world_size_in | ) |

Set the size of MPI_COMM_WORLD.

This function is only used if the linked program uses MPI4PY.

## Variable Documentation

## ◆ MDI_Get_language_execute_command

int(*)(void*, MDI_Comm, void*) MDI_Get_language_execute_command(MDI_Comm comm)

Get the language execute_command function needed by a language wrapper.

The function returns a function pointer to the execute_command function.

Parameters

  [out] | execute_command | Execute command callback
  [in] | comm | MDI communicator