Classes | Public Member Functions | Static Public Member Functions | Protected Attributes | Private Member Functions | Private Attributes | Friends | List of all members
PLMD::OFile Class Reference

#include <OFile.h>

Inheritance diagram for PLMD::OFile:
Inheritance graph
[legend]

Classes

class  Field
 Class identifying a single field for fielded output. More...
 

Public Member Functions

 OFile ()
 Constructor. More...
 
OFileaddConstantField (const std::string &)
 
void backupAllFiles (const std::string &str)
 This backs up all the files that would have been created with the name str. More...
 
void backupFile (const std::string &bstring, const std::string &fname)
 Backup a file by giving it a different name. More...
 
OFileclearFields ()
 Resets the list of fields. More...
 
void close ()
 Closes the file Should be used only for explicitely opened files. More...
 
OFileenforceBackup ()
 Enforce backup, even if the attached plumed object is restarting. More...
 
OFileenforceRestart ()
 Enforce restart, also if the attached plumed object is not restarting. More...
 
FileBaseenforceSuffix (const std::string &suffix)
 Enforce suffix. More...
 
bool FileExist (const std::string &path)
 Check if the file exists. More...
 
FileBaseflush () override
 Flush a file. More...
 
OFilefmtField ()
 Reset the format for writing double precision fields to its default. More...
 
OFilefmtField (const std::string &)
 Set the format for writing double precision fields. More...
 
FILE * getFILE () const
 Get the underlying file pointer. More...
 
std::string getMode () const
 Retrieve the mode. More...
 
std::string getPath () const
 Retrieve the path. More...
 
std::string getSuffix () const
 Get the file suffix. More...
 
bool isOpen ()
 Check if a file is open. More...
 
FileBaselink (Action &)
 Link to an Action object. More...
 
FileBaselink (Action &)
 Allows overloading of link. More...
 
FileBaselink (Communicator &)
 Link to a Communicator object. More...
 
FileBaselink (Communicator &)
 Allows overloading of link. More...
 
FileBaselink (FILE *)
 Link to an already open filed. More...
 
FileBaselink (FILE *)
 Allows overloading of link. More...
 
OFilelink (OFile &)
 Allows linking this OFile to another one. More...
 
FileBaselink (PlumedMain &)
 Link to a PlumedMain object Automatically links also the corresponding Communicator. More...
 
FileBaselink (PlumedMain &)
 Allows overloading of link. More...
 
OFileopen (const std::string &name) override
 Opens the file using automatic append/backup. More...
 
virtual FileBaseopen (const std::string &name)=0
 Allows overloading of open. More...
 
 operator bool () const
 Check for error/eof. More...
 
int printf (const char *fmt,...)
 Formatted output with explicit format - a la printf. More...
 
OFileprintField ()
 Close a line. More...
 
OFileprintField (const std::string &, const std::string &)
 Set the value of a string field. More...
 
OFileprintField (const std::string &, double)
 Set the value of a double precision field. More...
 
OFileprintField (const std::string &, int)
 Set the value of a int type field. More...
 
OFileprintField (const std::string &, long int)
 
OFileprintField (const std::string &, long unsigned)
 
OFileprintField (const std::string &, unsigned)
 
OFileprintField (Value *val, const double &v)
 Print a value. More...
 
OFilerewind ()
 Rewind a file. More...
 
void setBackupString (const std::string &)
 Set the string name to be used for automatic backup. More...
 
void setHeavyFlush ()
 Set heavyFlush flag. More...
 
OFilesetLinePrefix (const std::string &)
 Set the prefix for output. More...
 
OFilesetupPrintValue (Value *val)
 Used to setup printing of values. More...
 

Static Public Member Functions

static std::string appendSuffix (const std::string &path, const std::string &suffix)
 Append suffix. More...
 

Protected Attributes

Actionaction
 pointer to corresponding action. NULL if not linked More...
 
bool cloned
 Control closing on destructor. More...
 
Communicatorcomm
 communicator. NULL if not set More...
 
bool eof
 Set to true when end of file is encountered. More...
 
bool err
 Set to true when error is encountered. More...
 
FILE * fp
 file pointer More...
 
void * gzfp
 zip file pointer. More...
 
bool heavyFlush
 Set to true if you want flush to be heavy (close/reopen) More...
 
std::string mode
 mode of the opened file More...
 
std::string path
 path of the opened file More...
 
PlumedMainplumed
 pointer to main plumed object. NULL if not linked More...
 

Private Member Functions

bool checkRestart () const
 check if we are restarting More...
 
unsigned findField (const std::string &name) const
 Find field index given name. More...
 
size_t llwrite (const char *, size_t)
 Low-level write. More...
 

Private Attributes

int actual_buffer_length
 This variables stores the actual buffer length. More...
 
std::string backstring
 The string used for backing up files. More...
 
std::unique_ptr< char[]> buffer
 Internal buffer (generic use) More...
 
std::unique_ptr< char[]> buffer_string
 Internal buffer for printf. More...
 
int buflen
 Internal buffer length. More...
 
std::vector< Fieldconst_fields
 All the defined constant fields. More...
 
bool enforceBackup_
 True if backup behavior (i.e. non restart) should be forced. More...
 
std::string enforcedSuffix
 Enforced suffix: More...
 
bool enforcedSuffix_
 If true, use enforcedSuffix, else get it from PlumedMain. More...
 
bool enforceRestart_
 True if restart behavior should be forced. More...
 
bool fieldChanged
 True if fields has changed. More...
 
std::string fieldFmt
 Format for fields writing. More...
 
std::vector< Fieldfields
 All the defined variable fields. More...
 
std::string linePrefix
 Prefix for line (e.g. "PLUMED: ") More...
 
OFilelinked
 Pointer to a linked OFile. More...
 
std::ostringstream oss
 Temporary ostringstream for << output. More...
 
std::vector< Fieldprevious_fields
 All the previously defined variable fields. More...
 

Friends

template<class T >
OFileoperator<< (OFile &, const T &)
 Formatted output with << operator. More...
 

Detailed Description

Class for output files

This class provides features similar to those in the standard C "FILE*" type, but only for sequential output. See IFile for sequential input.

See the example here for a possible use:

#include "File.h"

int main(){
  PLMD::OFile pof;
  pof.open("ciao");
  pof.printf("%s\n","test1");
  pof.setLinePrefix("plumed: ");
  pof.printf("%s\n","test2");
  pof.setLinePrefix("");
  pof.addConstantField("x2").printField("x2",67.0);
  pof.printField("x1",10.0).printField("x3",20.12345678901234567890).printField();
  pof.printField("x1",10.0).printField("x3",-1e70*20.12345678901234567890).printField();
  pof.printField("x3",10.0).printField("x2",777.0).printField("x1",-1e70*20.12345678901234567890).printField();
  pof.printField("x3",67.0).printField("x1",18.0).printField();
  return 0;
}

This program is expected to produce a file "ciao" which reads

test1
plumed: test2
#! FIELDS x1 x3
#! SET x2                      67
                     10      20.12345678901234
                     10 -2.012345678901235e+71
#! FIELDS x1 x3
#! SET x2                     777
 -2.012345678901235e+71                     10
                     18                     67

Notes

Using correctly OFile in PLUMED

When a OFile object is used in PLUMED it can be convenient to link() it to the Action object where it is defined, or to the PlumedMain object. This will save in the OFile a pointer to the linked object and will allow to have some extra information. E.g., if PLUMED is restarting, files will be appended. Notice that one can enforce this behavior using the enforceRestart() method before opening a file.

To have all files managed consistently, it is important to use OFile in the proper way. This should allow multi-replica plumed, restart and backups to work in the expected way. For this reason all the operations in OFile and IFile are synchronizing all the processors of the group, so call to OFile functions should always be performed by all processes; for this reason is also not useful to use Log for debugging because only master threads will actually write. For debugging is better to use the standard stderr.

int main(){
// this is a growing file, containing a full history
// (frames are appended, as in traditional HILLS and COLVAR)
  OFile grw;
// this is a single-snapshopt file used e.g. for checkpointing
// (rewritten every time)
  OFile snp;

// open both files at the beginning
// (will go in \ref Action constructor)
  grw.open("growing");
  snp.open("snapshot");

// trajectory loop
  for(int i=0;i<nsteps;i++){

// files should be written in the update() method of an \ref Action

// write on growing file
    grw<<"data at step "<<i<<\n";

// flushing
// it takes time, so do it only if data is critical
// better to leave this choice to the user with the FLUSH keyword
//    grw.flush();

// write on snapshot file
    snp.rewind();
    snp<<"snapshot at step "<<i<<"\n";
    snp.flush();
// the only difference is that snp is rewound
// notice that it should be rewound just before writing
// because rewind is going to move the file out of the way
// to have a safe copy of the file ("bck.last.filename")
// Also notice that snapshots should be flushed
// for this reason, it is better to write them only
// rarely to avoid excessive slow down

  }
}

\notice
Notice that it is not necessary to explicitely close files, since they are closed implicitly
when the object goes out of scope. In case you need to explicitly close the file before it is
destroyed, please check it the procedure is exception safe and, if necessary, add some `try/catch`
statement.

Constructor & Destructor Documentation

◆ OFile()

PLMD::OFile::OFile ( )

Constructor.

Member Function Documentation

◆ addConstantField()

OFile & PLMD::OFile::addConstantField ( const std::string &  name)

◆ appendSuffix()

std::string PLMD::FileBase::appendSuffix ( const std::string &  path,
const std::string &  suffix 
)
staticinherited

Append suffix.

It appends the desired suffix to the string. Notice that it conserves some suffix (e.g. gz/xtc/trr).

◆ backupAllFiles()

void PLMD::OFile::backupAllFiles ( const std::string &  str)

This backs up all the files that would have been created with the name str.

It is used in analysis when you are not restarting. Analysis output files at different times, which are names analysis.0.<filename>, analysis.1.<filename> and <filename>, are backed up to bck.0.analysis.0.<filename>, bck.0.analysis.1.<filename> and bck.0.<filename>

◆ backupFile()

void PLMD::OFile::backupFile ( const std::string &  bstring,
const std::string &  fname 
)

Backup a file by giving it a different name.

◆ checkRestart()

bool PLMD::OFile::checkRestart ( ) const
private

check if we are restarting

◆ clearFields()

OFile & PLMD::OFile::clearFields ( )

Resets the list of fields.

As it is only possible to add new constant fields (addConstantField()), this method can be used to clean the field list.

◆ close()

void PLMD::FileBase::close ( )
inherited

Closes the file Should be used only for explicitely opened files.

◆ enforceBackup()

OFile & PLMD::OFile::enforceBackup ( )

Enforce backup, even if the attached plumed object is restarting.

◆ enforceRestart()

OFile & PLMD::OFile::enforceRestart ( )

Enforce restart, also if the attached plumed object is not restarting.

Useful for tests

◆ enforceSuffix()

FileBase & PLMD::FileBase::enforceSuffix ( const std::string &  suffix)
inherited

Enforce suffix.

Overrides the one set in PlumedMain&

◆ FileExist()

bool PLMD::FileBase::FileExist ( const std::string &  path)
inherited

Check if the file exists.

◆ findField()

unsigned PLMD::OFile::findField ( const std::string &  name) const
private

Find field index given name.

◆ flush()

FileBase & PLMD::OFile::flush ( )
overridevirtual

Flush a file.

Reimplemented from PLMD::FileBase.

◆ fmtField() [1/2]

OFile & PLMD::OFile::fmtField ( )

Reset the format for writing double precision fields to its default.

◆ fmtField() [2/2]

OFile & PLMD::OFile::fmtField ( const std::string &  fmt)

Set the format for writing double precision fields.

◆ getFILE()

FILE * PLMD::FileBase::getFILE ( ) const
inlineinherited

Get the underlying file pointer.

It might be null even if the file is open, e.g. when the file was open as a gzipped file.

◆ getMode()

std::string PLMD::FileBase::getMode ( ) const
inlineinherited

Retrieve the mode.

◆ getPath()

std::string PLMD::FileBase::getPath ( ) const
inlineinherited

Retrieve the path.

◆ getSuffix()

std::string PLMD::FileBase::getSuffix ( ) const
inherited

Get the file suffix.

◆ isOpen()

bool PLMD::FileBase::isOpen ( )
inherited

Check if a file is open.

◆ link() [1/9]

FileBase & PLMD::FileBase::link ( Action action)
inherited

Link to an Action object.

Automatically links also the corresponding PlumedMain and Communicator.

◆ link() [2/9]

FileBase & PLMD::FileBase::link

Allows overloading of link.

◆ link() [3/9]

FileBase & PLMD::FileBase::link ( Communicator comm)
inherited

Link to a Communicator object.

◆ link() [4/9]

FileBase & PLMD::FileBase::link

Allows overloading of link.

◆ link() [5/9]

FileBase & PLMD::FileBase::link ( FILE *  fp)
inherited

Link to an already open filed.

◆ link() [6/9]

FileBase & PLMD::FileBase::link

Allows overloading of link.

◆ link() [7/9]

OFile & PLMD::OFile::link ( OFile l)

Allows linking this OFile to another one.

In this way, everything written to this OFile will be immediately written on the linked OFile. Notice that a OFile should be either opened explicitly, linked to a FILE or linked to a OFile

◆ link() [8/9]

FileBase & PLMD::FileBase::link ( PlumedMain plumed)
inherited

Link to a PlumedMain object Automatically links also the corresponding Communicator.

◆ link() [9/9]

FileBase & PLMD::FileBase::link

Allows overloading of link.

◆ llwrite()

size_t PLMD::OFile::llwrite ( const char *  ptr,
size_t  s 
)
private

Low-level write.

◆ open() [1/2]

OFile & PLMD::OFile::open ( const std::string &  name)
overridevirtual

Opens the file using automatic append/backup.

Implements PLMD::FileBase.

◆ open() [2/2]

virtual FileBase& PLMD::FileBase::open

Allows overloading of open.

◆ operator bool()

PLMD::FileBase::operator bool ( ) const
inherited

Check for error/eof.

◆ printf()

int PLMD::OFile::printf ( const char *  fmt,
  ... 
)

Formatted output with explicit format - a la printf.

◆ printField() [1/8]

OFile & PLMD::OFile::printField ( )

Close a line.

Typically used as

  of.printField("a",a).printField("b",b).printField();

◆ printField() [2/8]

OFile & PLMD::OFile::printField ( const std::string &  name,
const std::string &  v 
)

Set the value of a string field.

◆ printField() [3/8]

OFile & PLMD::OFile::printField ( const std::string &  name,
double  v 
)

Set the value of a double precision field.

◆ printField() [4/8]

OFile & PLMD::OFile::printField ( const std::string &  name,
int  v 
)

Set the value of a int type field.

◆ printField() [5/8]

OFile & PLMD::OFile::printField ( const std::string &  name,
long int  v 
)

◆ printField() [6/8]

OFile & PLMD::OFile::printField ( const std::string &  name,
long unsigned  v 
)

◆ printField() [7/8]

OFile & PLMD::OFile::printField ( const std::string &  name,
unsigned  v 
)

◆ printField() [8/8]

OFile & PLMD::OFile::printField ( Value val,
const double &  v 
)

Print a value.

◆ rewind()

OFile & PLMD::OFile::rewind ( )

Rewind a file.

◆ setBackupString()

void PLMD::OFile::setBackupString ( const std::string &  str)

Set the string name to be used for automatic backup.

◆ setHeavyFlush()

void PLMD::FileBase::setHeavyFlush ( )
inlineinherited

Set heavyFlush flag.

◆ setLinePrefix()

OFile & PLMD::OFile::setLinePrefix ( const std::string &  l)

Set the prefix for output.

Typically "PLUMED: ". Notice that lines with a prefix cannot be parsed using fields in a IFile.

◆ setupPrintValue()

OFile & PLMD::OFile::setupPrintValue ( Value val)

Used to setup printing of values.

Friends And Related Function Documentation

◆ operator<<

template<class T >
OFile& operator<< ( OFile of,
const T &  t 
)
friend

Formatted output with << operator.

Member Data Documentation

◆ action

Action* PLMD::FileBase::action
protectedinherited

pointer to corresponding action. NULL if not linked

◆ actual_buffer_length

int PLMD::OFile::actual_buffer_length
private

This variables stores the actual buffer length.

◆ backstring

std::string PLMD::OFile::backstring
private

The string used for backing up files.

◆ buffer

std::unique_ptr<char[]> PLMD::OFile::buffer
private

Internal buffer (generic use)

◆ buffer_string

std::unique_ptr<char[]> PLMD::OFile::buffer_string
private

Internal buffer for printf.

◆ buflen

int PLMD::OFile::buflen
private

Internal buffer length.

◆ cloned

bool PLMD::FileBase::cloned
protectedinherited

Control closing on destructor.

If true, file will not be closed in destructor

◆ comm

Communicator* PLMD::FileBase::comm
protectedinherited

communicator. NULL if not set

◆ const_fields

std::vector<Field> PLMD::OFile::const_fields
private

All the defined constant fields.

◆ enforceBackup_

bool PLMD::OFile::enforceBackup_
private

True if backup behavior (i.e. non restart) should be forced.

◆ enforcedSuffix

std::string PLMD::FileBase::enforcedSuffix
privateinherited

Enforced suffix:

◆ enforcedSuffix_

bool PLMD::FileBase::enforcedSuffix_
privateinherited

If true, use enforcedSuffix, else get it from PlumedMain.

◆ enforceRestart_

bool PLMD::OFile::enforceRestart_
private

True if restart behavior should be forced.

◆ eof

bool PLMD::FileBase::eof
protectedinherited

Set to true when end of file is encountered.

◆ err

bool PLMD::FileBase::err
protectedinherited

Set to true when error is encountered.

◆ fieldChanged

bool PLMD::OFile::fieldChanged
private

True if fields has changed.

This could be due to a change in the list of fields or a reset of a nominally constant field

◆ fieldFmt

std::string PLMD::OFile::fieldFmt
private

Format for fields writing.

◆ fields

std::vector<Field> PLMD::OFile::fields
private

All the defined variable fields.

◆ fp

FILE* PLMD::FileBase::fp
protectedinherited

file pointer

◆ gzfp

void* PLMD::FileBase::gzfp
protectedinherited

zip file pointer.

◆ heavyFlush

bool PLMD::FileBase::heavyFlush
protectedinherited

Set to true if you want flush to be heavy (close/reopen)

◆ linePrefix

std::string PLMD::OFile::linePrefix
private

Prefix for line (e.g. "PLUMED: ")

◆ linked

OFile* PLMD::OFile::linked
private

Pointer to a linked OFile.

see link(OFile&)

◆ mode

std::string PLMD::FileBase::mode
protectedinherited

mode of the opened file

◆ oss

std::ostringstream PLMD::OFile::oss
private

Temporary ostringstream for << output.

◆ path

std::string PLMD::FileBase::path
protectedinherited

path of the opened file

◆ plumed

PlumedMain* PLMD::FileBase::plumed
protectedinherited

pointer to main plumed object. NULL if not linked

◆ previous_fields

std::vector<Field> PLMD::OFile::previous_fields
private

All the previously defined variable fields.


The documentation for this class was generated from the following files: