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
	)

Parameters

p	The C handler
c	The 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 )

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
	)

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

Parameters

p	The plumed object on which command is acting
key	The name of the command to be executed
val	The 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
	)

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 )

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 )

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 ( )

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 )

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 )

Returns: The constructed plumed object

◆ plumed_create_reference_v()

plumed plumed_create_reference_v ( void * v )

Returns: The constructed plumed object

◆ plumed_f2c()

plumed plumed_f2c ( const char * c )

Parameters

c	The 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 )

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

Parameters

p	The plumed object to be deallocated

◆ plumed_gcmd()

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

Parameters

key	The name of the command to be executed
val	The 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 )

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

◆ plumed_gfinalize()

void plumed_gfinalize ( void )

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 )

Returns: 1 if plumed has been initialized, 0 otherwise

◆ plumed_global()

plumed plumed_global ( void )

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 ( )

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 )

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 )

◆ plumed_v2c()

plumed plumed_v2c ( void * )

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 )

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:

wrapper/Plumed.h

Private Attributes

Related Functions

Detailed Description

Friends And Related Function Documentation

◆ plumed_c2f()

◆ plumed_c2v()

◆ plumed_cmd()

◆ plumed_cmd_nothrow()

◆ plumed_create()

◆ plumed_create_dlopen()

◆ plumed_create_invalid()

◆ plumed_create_reference()

◆ plumed_create_reference_f()

◆ plumed_create_reference_v()

◆ plumed_f2c()

◆ plumed_finalize()

◆ plumed_gcmd()

◆ plumed_gcreate()

◆ plumed_gfinalize()

◆ plumed_ginitialized()

◆ plumed_global()

◆ plumed_gvalid()

◆ plumed_installed()

◆ plumed_use_count()

◆ plumed_v2c()

◆ plumed_valid()

Member Data Documentation

◆ p