Private Attributes | Related Functions | List of all members
plumed Struct Reference

Main plumed object. More...

#include <Plumed.h>

Private Attributes

void * p
 Void pointer holding the real PlumedMain structure. More...
 

Related Functions

(Note that these are not member functions.)

void plumed_c2f (plumed p, char *c)
 Converts a C handler to a FORTRAN handler. More...
 
void * plumed_c2v (plumed p)
 Converts a plumed object to a void pointer. Available as of PLUMED 2.5. More...
 
void plumed_cmd (plumed p, const char *key, const void *val)
 Tells p to execute a command. More...
 
void plumed_cmd_nothrow (plumed p, const char *key, const void *val, plumed_nothrow_handler nothrow)
 Same as plumed_cmd, but does not throw exceptions. More...
 
plumed plumed_create (void)
 Constructor. More...
 
plumed plumed_create_dlopen (const char *path)
 Constructor from path. Available as of PLUMED 2.5. More...
 
plumed plumed_create_invalid ()
 Constructor as invalid. Available as of PLUMED 2.5. More...
 
plumed plumed_create_reference (plumed p)
 
plumed plumed_create_reference_f (const char *f)
 Create a new reference to an existing object passed as a fortran string, increasing its reference count. Available as of PLUMED 2.5. More...
 
plumed plumed_create_reference_v (void *v)
 Create a new reference to an existing object passed as a void pointer, increasing its reference count. Available as of PLUMED 2.5. More...
 
plumed plumed_f2c (const char *c)
 Converts a FORTRAN handler to a C handler. More...
 
void plumed_finalize (plumed p)
 Destructor. More...
 
void plumed_gcmd (const char *key, const void *val)
 Tells to the global interface to execute a command. More...
 
void plumed_gcreate (void)
 Constructor for the global interface. More...
 
void plumed_gfinalize (void)
 Destructor for the global interface. More...
 
int plumed_ginitialized (void)
 Check if the global interface has been initialized. More...
 
plumed plumed_global (void)
 Retrieves an handler to the global structure. More...
 
int plumed_gvalid ()
 Check if global plumed object is valid. Available as of PLUMED 2.5. More...
 
int plumed_installed (void)
 Check if plumed is installed (for runtime binding). More...
 
int plumed_use_count (plumed p)
 Returns the number of references to the underlying object. Available as of PLUMED 2.5. More...
 
plumed plumed_v2c (void *)
 Converts a void pointer to a plumed object. Available as of PLUMED 2.5. More...
 
int plumed_valid (plumed p)
 Check if plumed object is valid. Available as of PLUMED 2.5. More...
 

Detailed Description

Main plumed object.

This is an object containing a Plumed instance, which should be used in the MD engine. It should first be initialized with plumed_create(), then it communicates with the MD engine using plumed_cmd(). Finally, before the termination, it should be deallocated with plumed_finalize(). Its interface is very simple and general, and is expected not to change across plumed versions. See Reference for interfacing MD codes with PLUMED.

Friends And Related Function Documentation

◆ plumed_c2f()

void plumed_c2f ( plumed  p,
char *  c 
)
related

Converts a C handler to a FORTRAN handler.

Parameters
pThe C handler
cThe FORTRAN handler (a char[32])

This function can be used to convert a plumed object created in C to a plumed handler that can be used in FORTRAN. Notice that the reference counter is not incremented. In other words, the FORTRAN object will be a weak reference. If you later finalize the C handler, the FORTRAN handler will be invalid.

#include <plumed/wrapper/Plumed.h>
int main(int argc,char*argv[]){
  plumed p;
  p=plumed_create();
  char fortran_handler[32];
  plumed_c2f(p,fortran_handler);
  printf("DEBUG: this is a string representation for the plumed handler: %s\n",fortran_handler);
  fortran_routine(fortran_handler);
  plumed_finalize(p);
  return 0;
}

Here fortran_routine is a routine implemented in FORTRAN that manipulates the fortran_handler.

◆ plumed_c2v()

void * plumed_c2v ( plumed  p)
related

Converts a plumed object to a void pointer. Available as of PLUMED 2.5.

It returns a void pointer that can be converted back to a plumed object using plumed_v2c. When compiling without NDEBUG, it checks if the plumed object was properly created. Notice that an invalid object (see plumed_valid) can be converted to void* and back.

Can be used to store a reference to a plumed object without including the Plumed.h header.

◆ plumed_cmd()

void plumed_cmd ( plumed  p,
const char *  key,
const void *  val 
)
related

Tells p to execute a command.

If the object is not valid (see plumed_valid), this command will exit.

Parameters
pThe plumed object on which command is acting
keyThe name of the command to be executed
valThe argument. It is declared as const to allow calls like plumed_cmd(p,"A","B"), but for some choice of key it can change the content.

Notice that within PLUMED we use a const_cast to remove any const qualifier from the second argument of plumed_cmd.

In some cases val can be omitted: just pass a NULL pointer (in C++, val is optional and can be omitted, or you can equivalently pass NULL or nullptr). The set of possible keys is the real API of the plumed library, and will be expanded with time. New commands will be added, but backward compatibility will be retained as long as possible.

◆ plumed_cmd_nothrow()

void plumed_cmd_nothrow ( plumed  p,
const char *  key,
const void *  val,
plumed_nothrow_handler  nothrow 
)
related

Same as plumed_cmd, but does not throw exceptions.

This function is meant to be used when errors should be handled explicitly. if an exception is raised within PLUMED, the function nothrow.handler() will be called with arguments (nothrow.ptr,code,message,opt). This allows the C++ interface to correctly rethrow exceptions, but might be used from C as well. opt can be used to pass further information (not used yet).

◆ plumed_create()

plumed plumed_create ( void  )
related

Constructor.

Constructs a plumed object.

Notice that if you are linking against libplumedWrapper.a, if you are using a code patched in runtime mode, or if you are including the Plumed.c file directly in your code, this constructor might return an invalid plumed object. In particular, this could happen if the PLUMED_KERNEL environment variable is not set or set incorrectly. In order to detect an incorrect plumed object you might use plumed_valid() on the resulting object. Alternatively, if you use plumed_cmd() on an invalid plumed object the code will exit. Also notice that to avoid memory leaks you should call plumed_finalize() to finalize a plumed object even if it is invalid:

  plumed p=plumed_create();
  if(!plumed_valid(p)) {
// this will happen if the PLUMED_KERNEL variable is not set correctly
    plumed_finalize(p);
    return whatever;
  }
\return The constructed plumed object

◆ plumed_create_dlopen()

plumed plumed_create_dlopen ( const char *  path)
related

Constructor from path. Available as of PLUMED 2.5.

It tries to construct a plumed object loading the kernel located at path. Notice that it could leave the resulting object in an invalid state. In order to detect an invalid plumed object you might use plumed_valid() on the resulting object. Alternatively, if you use plumed_cmd() on an invalid plumed object the code will exit.

Also notice that to avoid memory leaks you should call plumed_finalize() to finalize a plumed object even if it is invalid.

  plumed p=plumed_create(path);
  if(!plumed_valid(p)) {
// this will happen if the path argument is not set correctly
    plumed_finalize(p);
    return whatever;
  }
\return The constructed plumed object

◆ plumed_create_invalid()

plumed plumed_create_invalid ( )
related

Constructor as invalid. Available as of PLUMED 2.5.

Can be used to create an object in the same state as if it was returned by plumed_create_dlopen with an incorrect path (or plumed_create using runtime binding and an incorrect PLUMED_KERNEL).

Can be used to initialize a plumed object to a well-defined state without explicitly creating it. The resulting object can be checked later with plumed_valid. Consider the following example

    plumed p;
    p=plumed_create_invalid();
// at this point p is initialized to a well-defined (invalid) state.
    setenv("PLUMED_KERNEL","/path/to/kernel/libplumedKernel.so",1);
    plumed_finalize(p);
    p=plumed_create();
\return The constructed plumed object

◆ plumed_create_reference()

plumed plumed_create_reference ( plumed  p)
related

Create a new reference to an existing object, increasing its reference count. Available as of PLUMED 2.5

Use it to increase by one the reference count of a plumed object. The resulting pointer might be identical to the one passed as an argument, but the reference count will be incremented by one. Notice that you should finalize the resulting object.

  plumed p1;
  plumed p2;
  p1=plumed_create();
  p2=plumed_create_reference(p1);
  plumed_finalize(p1);
// now you can still use p2
  plumed_cmd(p2,"init",NULL);
  plumed_finalize(p2);
// now the underlying object is destroyed.
If the `p` object is invalid, also the returned object will be invalid.

\param p The plumed object that will be referenced to.
\return The constructed plumed object

◆ plumed_create_reference_f()

plumed plumed_create_reference_f ( const char *  f)
related

Create a new reference to an existing object passed as a fortran string, increasing its reference count. Available as of PLUMED 2.5.

Returns
The constructed plumed object

◆ plumed_create_reference_v()

plumed plumed_create_reference_v ( void *  v)
related

Create a new reference to an existing object passed as a void pointer, increasing its reference count. Available as of PLUMED 2.5.

Returns
The constructed plumed object

◆ plumed_f2c()

plumed plumed_f2c ( const char *  c)
related

Converts a FORTRAN handler to a C handler.

Parameters
cThe FORTRAN handler (a char[32])
Returns
The C handler

This function can be used to convert a plumed object created in FORTRAN to a plumed handler that can be used in C. Notice that the reference counter is not incremented. In other words, the C object will be a weak reference. If you later finalize the FORTRAN handler, the C handler will be invalid.

void c_routine(char handler[32]){
  plumed p;
  p=plumed_f2c(handler);
  plumed_cmd(p,"init",NULL);
}

Here c_routine is a C function that can be called from FORTRAN and interact with the provided plumed handler.

◆ plumed_finalize()

void plumed_finalize ( plumed  p)
related

Destructor.

It must be used for any object created using plumed_create(), even if the created object is not valid.

Parameters
pThe plumed object to be deallocated

◆ plumed_gcmd()

void plumed_gcmd ( const char *  key,
const void *  val 
)
related

Tells to the global interface to execute a command.

Parameters
keyThe name of the command to be executed
valThe argument. It is declared as const to allow calls like plumed_gcmd("A","B"), but for some choice of key it can change the content

plumed_gcmd(a,b); is equivalent to plumed_cmd(plumed_global(),a,b);.

◆ plumed_gcreate()

void plumed_gcreate ( void  )
related

Constructor for the global interface.

Note
Equivalent to plumed_create(), but initialize the static global plumed object

◆ plumed_gfinalize()

void plumed_gfinalize ( void  )
related

Destructor for the global interface.

plumed_gfinalize(a,b); is similar to plumed_finalize(plumed_global(),a,b);, but not completely equivalent. In particular, plumed_gfinalize() also makes sure that the global object is reset to its initial status. After calling it, plumed_ginitialized() will thus return 0.

◆ plumed_ginitialized()

int plumed_ginitialized ( void  )
related

Check if the global interface has been initialized.

Returns
1 if plumed has been initialized, 0 otherwise

◆ plumed_global()

plumed plumed_global ( void  )
related

Retrieves an handler to the global structure.

You can use this if you work on a code that uses the global structure and you want to pass to a generic routine an handler to the same structure. E.g.

  plumed p=plumed_global();
  some_routine(p);

◆ plumed_gvalid()

int plumed_gvalid ( )
related

Check if global plumed object is valid. Available as of PLUMED 2.5.

It might return zero if plumed is not available at runtime.

Returns
1 if plumed is valid, 0 otherwise.

◆ plumed_installed()

int plumed_installed ( void  )
related

Check if plumed is installed (for runtime binding).

Notice that this is equivalent to creating a dummy object and checking if it is valid.

  // this:
  //int a=plumed_installed();
  // is equivalent to this:

  plumed p=plumed_create();
  int a=plumed_valid(p);
  plumed_finalize(p);
This function is mostly provided for compatibility with PLUMED 2.4, where \ref plumed_valid()
was not available. Using \ref plumed_valid() is now preferred since it creates a single object
instead of creating a dummy object that is then discarded.

\return 1 if plumed is installed, 0 otherwise

◆ plumed_use_count()

int plumed_use_count ( plumed  p)
related

Returns the number of references to the underlying object. Available as of PLUMED 2.5.

◆ plumed_v2c()

plumed plumed_v2c ( void *  )
related

Converts a void pointer to a plumed object. Available as of PLUMED 2.5.

It returns a plumed object from a void pointer obtained with plumed_c2v. When compiling without NDEBUG, it checks if the plumed object was properly created.

Can be used to store a reference to a plumed object without including the Plumed.h header.

◆ plumed_valid()

int plumed_valid ( plumed  p)
related

Check if plumed object is valid. Available as of PLUMED 2.5.

It might return false if plumed is not available at runtime.

Returns
1 if plumed is valid, 0 otherwise

Member Data Documentation

◆ p

void* plumed::p
private

Void pointer holding the real PlumedMain structure.

To maintain binary compatibility, we should not add members to this structure. As of PLUMED 2.5, in order to add new components we do not store the pointer to PlumedMain here but rather a pointer to an intermediate private structure that contains all the details.


The documentation for this struct was generated from the following file: