sjef
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
sjef::Project Class Reference

#include <sjef.h>

Public Types

using run_list_t = std::vector< std::string >
 Obtain the list of run directory names. More...
 

Public Member Functions

 Project (const std::filesystem::path &filename, bool construct=true, const std::string &default_suffix="", const mapstringstring_t &suffixes={{"inp", "inp"}, {"out", "out"}, {"xml", "xml"}})
 Construct, or attach to, a Molpro project bundle. More...
 
 Project (const Project &source)=delete
 
 Project (const Project &&source)=delete
 
virtual ~Project ()
 
bool copy (const std::filesystem::path &destination_filename, bool force=false, bool keep_hash=false, bool slave=false, int keep_run_directories=std::numeric_limits< int >::max())
 Copy the project to another location. More...
 
bool move (const std::filesystem::path &destination_filename, bool force=false)
 Move the project to another location. More...
 
bool import_file (const std::filesystem::path &file, bool overwrite=false)
 Import one or more files into the project. In the case of a .xml output file, if the corresponding input file does not exist, it will be generated. More...
 
bool import_file (const std::vector< std::string > &files, bool overwrite=false)
 
bool export_file (const std::filesystem::path &file, bool overwrite=false)
 Export one or more files from the project. More...
 
bool export_file (const std::vector< std::string > &files, bool overwrite=false)
 
void set_warnings (const Logger::Levels level=Logger::Levels::warning, std::ostream &stream=std::cerr, std::vector< std::string > preambles={"sjef:: Error: ", "sjef:: Warning: ", "sjef:: Note:"})
 Set the warning/error diagnostic level and destination. More...
 
void set_verbosity (int verbosity, std::ostream &stream=std::cout)
 
bool run (int verbosity=0, bool force=false, bool wait=false, const std::string &options="")
 Start a sjef job. More...
 
bool run (const std::string &name, int verbosity=0, bool force=false, bool wait=false, const std::string &options="")
 
sjef::status status () const
 Obtain the status of the job started by run() More...
 
std::string status_message (int verbosity=0) const
 
void wait (unsigned int maximum_microseconds=10000) const
 Wait unconditionally for status() to return neither 'waiting' nor 'running'. More...
 
void kill (int verbosity=0)
 Kill the job started by run() More...
 
bool run_needed (int verbosity=0) const
 Check whether the job output is believed to be out of date with respect to the input and any other files contained in the project that might be used in the job. More...
 
std::string input_from_output (bool sync=true) const
 If possible, construct the input embedded in the output file. More...
 
int local_pid_from_output () const
 Try to get the process id of the job from its output, if the running program happens to offer that. More...
 
sjef::status status_from_output () const
 Obtain the job status, if possible, by examining the output. More...
 
void rewrite_input_file (const std::string &input_file_name, const std::string &old_name)
 
void custom_initialisation ()
 Perform any project initialisation specific to the project suffix. More...
 
void custom_run_preface ()
 Before launching a job, perform any required actions specific to the project suffix. More...
 
std::string xml (int run=0, bool sync=true) const
 Get the xml output, completing any open tags if necessary. More...
 
std::string file_contents (const std::string &suffix="", const std::string &name="", int run=0, bool sync=true) const
 Obtain the contents of a project file. More...
 
void clean (int keep_run_directories=1)
 Remove run directories from project. More...
 
void property_set (const std::string &property, const std::string &value)
 Set a property. More...
 
void property_set (const mapstringstring_t &properties)
 Set one or more properties. More...
 
std::string property_get (const std::string &property) const
 Get the value of a property. More...
 
mapstringstring_t property_get (const std::vector< std::string > &properties) const
 Get the values of several properties. More...
 
void property_delete (const std::string &property)
 Remove a variable. More...
 
void property_delete (const std::vector< std::string > &properties)
 
std::vector< std::string > property_names () const
 Get the names of all assigned properties. More...
 
std::filesystem::path filename (std::string suffix="", const std::string &name="", int run=-1) const
 Get the file name of the bundle, or a primary file of particular type, or a general file in the bundle. More...
 
std::string filename_string (std::string suffix="", const std::string &name="", int run=-1) const
 
std::string run_directory_basename (int run=0) const
 
std::filesystem::path run_directory (int run=0) const
 Obtain the path of a run directory. More...
 
int run_verify (int run) const
 Check a run exists, and resolve most recent. More...
 
run_list_t run_list () const
 
std::filesystem::path run_directory_new ()
 Create a new run directory. Also copy into it the input file, and any of its dependencies. More...
 
void run_delete (int run)
 Delete a run directory. More...
 
std::string name () const
 
int recent_find (const std::filesystem::path &filename) const
 
std::string recent (int number=1) const
 
void change_backend (std::string backend=std::string{""}, bool force=false)
 Change the active backend. More...
 
const std::map< std::string, Backend > & backends () const
 
std::map< std::string, Backend > & backends ()
 
std::filesystem::path propertyFile () const
 
const std::string backend_cache () const
 Get the location of the backend cache. More...
 
size_t project_hash ()
 Return a globally-unique hash to identify the project. The hash is generated on first call to this function, and should be relied on to never change, including after calling move(). copy() normally results in a new hash string, but this can be overridden if an exact clone is really wanted. More...
 
size_t input_hash () const
 Construct a hash that is unique to the contents of the input file and anything it references. More...
 
std::string backend_get (const std::string &backend, const std::string &key) const
 Obtain the value of a field in a backend. More...
 
std::string backend_parameter_expand (const std::string &backend, std::string templ="") const
 Perform parameter substitution for a backend run_command template. More...
 
mapstringstring_t backend_parameters (const std::string &backend, bool doc=false) const
 Get all of the parameters referenced in the run_command of a backend. More...
 
void backend_parameter_set (const std::string &backend, const std::string &name, const std::string &value)
 
void backend_parameter_delete (const std::string &backend, const std::string &name)
 
std::string backend_parameter_get (const std::string &backend, const std::string &name) const
 
std::string backend_parameter_documentation (const std::string &backend, const std::string &name) const
 Return the documentation associated with a backend run parameter. More...
 
std::string backend_parameter_default (const std::string &backend, const std::string &name) const
 Return the default value associated with a backend run parameter. More...
 
std::vector< std::string > backend_names () const
 Get the names of all the backend objects associated with the object. More...
 
void add_backend (const std::string &name, const mapstringstring_t &fields)
 Introduce a new backend to the project and to the user's global backend configuration for all projects of the same type. More...
 
void delete_backend (const std::string &name)
 Remove a backend from the project and from the user's global backend configuration for all projects of the same type. More...
 
bool check_backend (const std::string &name) const
 Check whether the specification of a backend is valid. More...
 
bool check_all_backends () const
 Check the specification of all backends for validity. More...
 
void take_run_files (int run=0, const std::string &fromname="", const std::string &toname="") const
 Copy files from a run directory to the main project. More...
 
void set_current_run (unsigned int run=0)
 Set the focussed run directory. More...
 
unsigned int current_run () const
 Get the focussed run directory. More...
 
pugi::xpath_node_set select_nodes (const std::string &xpath_query, int run=0) const
 General XPath search on the xml document. Needs the pugixml library to parse the result. More...
 
std::vector< std::string > xpath_search (const std::string &xpath_query, const std::string &attribute="", int run=0) const
 Simple XPath search on the xml document. For each matching node found, return a string that contains the value of a specified attribute, or if the attribute is omitted, the node contents. More...
 
std::vector< std::string > xpath_xml (const std::string &xpath_query, int run=0) const
 Simple XPath search on the xml document. For each matching node found, return a string that contains a complete XML document with the node as root element. More...
 

Static Public Member Functions

static void erase (const std::filesystem::path &filename, const std::string &default_suffix="")
 Erase a project from the file system, and remove it from the recent projects file. More...
 
static int recent_find (const std::string &suffix, const std::filesystem::path &filename)
 Look for a project by name in the user-global recent project list. More...
 
static std::string recent (const std::string &suffix, int number=1)
 Look for a project by rank in the user-global recent project list. More...
 

Static Public Attributes

static const std::vector< std::string > suffix_keys
 

Friends

class util::Job
 

Member Typedef Documentation

◆ run_list_t

using sjef::Project::run_list_t = std::vector<std::string>

Obtain the list of run directory names.

Returns

Constructor & Destructor Documentation

◆ Project() [1/3]

sjef::Project::Project ( const std::filesystem::path &  filename,
bool  construct = true,
const std::string &  default_suffix = "",
const mapstringstring_t suffixes = {{"inp", "inp"}, {"out", "out"}, {"xml", "xml"}} 
)
explicit

Construct, or attach to, a Molpro project bundle.

Parameters
filenameThe file name of the bundle. If it does not have suffix .sjef, it will be forced to do so.
constructif false, do not actually build the project on disk. Can be used to generate the filename of the project.
default_suffixThe file extension to be used for the project directory name if filename does not have one
suffixesThe file suffixes for special (input, output) files within the project

◆ Project() [2/3]

sjef::Project::Project ( const Project source)
delete

◆ Project() [3/3]

sjef::Project::Project ( const Project &&  source)
delete

◆ ~Project()

virtual sjef::Project::~Project ( )
virtual

Member Function Documentation

◆ add_backend()

void sjef::Project::add_backend ( const std::string &  name,
const mapstringstring_t fields 
)

Introduce a new backend to the project and to the user's global backend configuration for all projects of the same type.

Parameters
nameThe name of the backend to be created. An existing backend of the same name will be overwritten
fieldsThe backend fields to be specified

◆ backend_cache()

const std::string sjef::Project::backend_cache ( ) const

Get the location of the backend cache.

Returns
host, path

◆ backend_get()

std::string sjef::Project::backend_get ( const std::string &  backend,
const std::string &  key 
) const

Obtain the value of a field in a backend.

Parameters
backend
key
Returns

◆ backend_names()

std::vector<std::string> sjef::Project::backend_names ( ) const

Get the names of all the backend objects associated with the object.

Returns

◆ backend_parameter_default()

std::string sjef::Project::backend_parameter_default ( const std::string &  backend,
const std::string &  name 
) const
inline

Return the default value associated with a backend run parameter.

Parameters
backendThe name of the backend
nameThe parameter
Returns

◆ backend_parameter_delete()

void sjef::Project::backend_parameter_delete ( const std::string &  backend,
const std::string &  name 
)
inline

◆ backend_parameter_documentation()

std::string sjef::Project::backend_parameter_documentation ( const std::string &  backend,
const std::string &  name 
) const
inline

Return the documentation associated with a backend run parameter.

Parameters
backendThe name of the backend
nameThe parameter
Returns

◆ backend_parameter_expand()

std::string sjef::Project::backend_parameter_expand ( const std::string &  backend,
std::string  templ = "" 
) const

Perform parameter substitution for a backend run_command template.

Parameters
backendThe name of the backend
templThe template to be expanded
  • {prologue text%param} is replaced by the value of project property Backend/backend/param if it is defined, prefixed by prologue text. Otherwise, the entire contents between {} is elided.
  • {prologue %param:default value} works similarly, with substitution of default value instead of elision if param is not defined. If templ is not specified, the run_command of backend will be used.
Returns
The expanded string

◆ backend_parameter_get()

std::string sjef::Project::backend_parameter_get ( const std::string &  backend,
const std::string &  name 
) const
inline

◆ backend_parameter_set()

void sjef::Project::backend_parameter_set ( const std::string &  backend,
const std::string &  name,
const std::string &  value 
)
inline

◆ backend_parameters()

mapstringstring_t sjef::Project::backend_parameters ( const std::string &  backend,
bool  doc = false 
) const

Get all of the parameters referenced in the run_command of a backend.

Parameters
backendThe name of the backend
docWhether to return documentation instead of default values
Returns
A map where the keys are the parameter names, and the values the defaults.

◆ backends() [1/2]

std::map<std::string, Backend>& sjef::Project::backends ( )
inline

◆ backends() [2/2]

const std::map<std::string, Backend>& sjef::Project::backends ( ) const
inline

◆ change_backend()

void sjef::Project::change_backend ( std::string  backend = std::string{""},
bool  force = false 
)

Change the active backend.

Parameters
backendThe name of the backend. If not a valid name, the function throws std::invalid_argument.
forceIf false, and the current backend is equal to backend, do nothing

◆ check_all_backends()

bool sjef::Project::check_all_backends ( ) const

Check the specification of all backends for validity.

Returns

◆ check_backend()

bool sjef::Project::check_backend ( const std::string &  name) const

Check whether the specification of a backend is valid.

Parameters
nameThe name of the backend to be checked.
Returns

◆ clean()

void sjef::Project::clean ( int  keep_run_directories = 1)

Remove run directories from project.

Parameters
keep_run_directoriesMaximum number of run directories to keep

◆ copy()

bool sjef::Project::copy ( const std::filesystem::path &  destination_filename,
bool  force = false,
bool  keep_hash = false,
bool  slave = false,
int  keep_run_directories = std::numeric_limits< int >::max() 
)

Copy the project to another location.

Parameters
destination_filename
forcewhether to first remove anything already existing at the new location
keep_hashwhether to clone the project_hash, or allow a fresh one to be generated
slaveif set, (a) omit copying the run directory (b) do not register the project in recent projects list
keep_run_directoriesKeep up to this number of run directories unless slave is set
Returns
true if the copy was successful

◆ current_run()

unsigned int sjef::Project::current_run ( ) const

Get the focussed run directory.

Returns
The run directory, or zero if there is no run directory yet.

◆ custom_initialisation()

void sjef::Project::custom_initialisation ( )

Perform any project initialisation specific to the project suffix.

◆ custom_run_preface()

void sjef::Project::custom_run_preface ( )

Before launching a job, perform any required actions specific to the project suffix.

◆ delete_backend()

void sjef::Project::delete_backend ( const std::string &  name)

Remove a backend from the project and from the user's global backend configuration for all projects of the same type.

Parameters
nameThe name of the backend to be removed.

◆ erase()

static void sjef::Project::erase ( const std::filesystem::path &  filename,
const std::string &  default_suffix = "" 
)
static

Erase a project from the file system, and remove it from the recent projects file.

◆ export_file() [1/2]

bool sjef::Project::export_file ( const std::filesystem::path &  file,
bool  overwrite = false 
)

Export one or more files from the project.

Parameters
fileThe relative or absolute path name of the destination; the base name will be used to locate the file in the project.
overwriteWhether to overwrite an existing file.

◆ export_file() [2/2]

bool sjef::Project::export_file ( const std::vector< std::string > &  files,
bool  overwrite = false 
)
inline

◆ file_contents()

std::string sjef::Project::file_contents ( const std::string &  suffix = "",
const std::string &  name = "",
int  run = 0,
bool  sync = true 
) const

Obtain the contents of a project file.

Parameters
suffixIf present without name, look for a primary file with that type. If absent, the file name of the bundle is instead selected
nameIf present, look for a file of this name, appended with .suffix if that is non-blank
runIf present, look for the file in a particular run directory. Otherwise it will search in the currently focussed run directory, and if not found, the main directory
syncWhether to force a synchronisation with backend before getting the file contents
Returns
the contents of the file

◆ filename()

std::filesystem::path sjef::Project::filename ( std::string  suffix = "",
const std::string &  name = "",
int  run = -1 
) const

Get the file name of the bundle, or a primary file of particular type, or a general file in the bundle.

Parameters
suffixIf present without name, look for a primary file with that type. If absent, the file name of the bundle is instead selected
nameIf present, look for a file of this name, appended with .suffix if that is non-blank
runIf specified, look in a run directory for the file, instead of the main project directory. A value of 0 is interpreted as the most recent run directory if there is one, otherwise the main project directory. A value of -1 means to use the main project directory.
Returns
the fully-qualified name of the file

◆ filename_string()

std::string sjef::Project::filename_string ( std::string  suffix = "",
const std::string &  name = "",
int  run = -1 
) const

◆ import_file() [1/2]

bool sjef::Project::import_file ( const std::filesystem::path &  file,
bool  overwrite = false 
)

Import one or more files into the project. In the case of a .xml output file, if the corresponding input file does not exist, it will be generated.

Parameters
file
overwriteWhether to overwrite an existing file.

◆ import_file() [2/2]

bool sjef::Project::import_file ( const std::vector< std::string > &  files,
bool  overwrite = false 
)
inline

◆ input_from_output()

std::string sjef::Project::input_from_output ( bool  sync = true) const

If possible, construct the input embedded in the output file.

Parameters
syncWhether to force a synchronisation with backend before getting the file contents
Returns
The input used to construct the output, or, if that can't be deduced, an empty string.

◆ input_hash()

size_t sjef::Project::input_hash ( ) const

Construct a hash that is unique to the contents of the input file and anything it references.

Returns
hash

◆ kill()

void sjef::Project::kill ( int  verbosity = 0)

Kill the job started by run()

◆ local_pid_from_output()

int sjef::Project::local_pid_from_output ( ) const

Try to get the process id of the job from its output, if the running program happens to offer that.

Returns
process id if available, otherwise -1

◆ move()

bool sjef::Project::move ( const std::filesystem::path &  destination_filename,
bool  force = false 
)

Move the project to another location.

Parameters
destination_filename
forcewhether to first remove anything already existing at the new location
Returns
true if the move was successful

◆ name()

std::string sjef::Project::name ( ) const
Returns
the base name of the project, ie its file name with directory and suffix stripped off

◆ project_hash()

size_t sjef::Project::project_hash ( )

Return a globally-unique hash to identify the project. The hash is generated on first call to this function, and should be relied on to never change, including after calling move(). copy() normally results in a new hash string, but this can be overridden if an exact clone is really wanted.

Returns
hash

◆ property_delete() [1/2]

void sjef::Project::property_delete ( const std::string &  property)

Remove a variable.

Parameters
property

◆ property_delete() [2/2]

void sjef::Project::property_delete ( const std::vector< std::string > &  properties)

◆ property_get() [1/2]

std::string sjef::Project::property_get ( const std::string &  property) const

Get the value of a property.

Parameters
property
Returns
The value, or "" if key does not exist

◆ property_get() [2/2]

mapstringstring_t sjef::Project::property_get ( const std::vector< std::string > &  properties) const

Get the values of several properties.

Parameters
properties
Returns
For each property found, a key-value pair

◆ property_names()

std::vector<std::string> sjef::Project::property_names ( ) const

Get the names of all assigned properties.

Returns

◆ property_set() [1/2]

void sjef::Project::property_set ( const mapstringstring_t properties)

Set one or more properties.

Parameters
propertiesKey-value pairs of properties to be set

◆ property_set() [2/2]

void sjef::Project::property_set ( const std::string &  property,
const std::string &  value 
)

Set a property.

Parameters
property
value

◆ propertyFile()

std::filesystem::path sjef::Project::propertyFile ( ) const

◆ recent() [1/2]

static std::string sjef::Project::recent ( const std::string &  suffix,
int  number = 1 
)
static

Look for a project by rank in the user-global recent project list.

Parameters
suffixthe project suffix
numberthe rank of the project (1 is newest)
Returns
the filename of the project, or "" if not found

◆ recent() [2/2]

std::string sjef::Project::recent ( int  number = 1) const

◆ recent_find() [1/2]

int sjef::Project::recent_find ( const std::filesystem::path &  filename) const

◆ recent_find() [2/2]

static int sjef::Project::recent_find ( const std::string &  suffix,
const std::filesystem::path &  filename 
)
static

Look for a project by name in the user-global recent project list.

Parameters
suffixthe project suffix
filename
Returns
0 if failure, otherwise the rank of the project (1 is newest)

◆ rewrite_input_file()

void sjef::Project::rewrite_input_file ( const std::string &  input_file_name,
const std::string &  old_name 
)

◆ run() [1/2]

bool sjef::Project::run ( const std::string &  name,
int  verbosity = 0,
bool  force = false,
bool  wait = false,
const std::string &  options = "" 
)
inline

◆ run() [2/2]

bool sjef::Project::run ( int  verbosity = 0,
bool  force = false,
bool  wait = false,
const std::string &  options = "" 
)

Start a sjef job.

Parameters
verbosityIf >0, show underlying processing
forceWhether to force submission of the job even though run_needed() reports that it's unnecessary
waitWhether to wait for the job to complete instead of returning after launching it
optionsAdditional options
Returns

◆ run_delete()

void sjef::Project::run_delete ( int  run)

Delete a run directory.

Parameters
run

◆ run_directory()

std::filesystem::path sjef::Project::run_directory ( int  run = 0) const

Obtain the path of a run directory.

Parameters
run
  • 0: the last used run directory, or, if there is no run directory, the main project directory
  • other: the specified run directory
Returns
the fully-qualified name of the directory

◆ run_directory_basename()

std::string sjef::Project::run_directory_basename ( int  run = 0) const

◆ run_directory_new()

std::filesystem::path sjef::Project::run_directory_new ( )

Create a new run directory. Also copy into it the input file, and any of its dependencies.

Returns
The sequence number of the new run directory

◆ run_list()

run_list_t sjef::Project::run_list ( ) const

◆ run_needed()

bool sjef::Project::run_needed ( int  verbosity = 0) const

Check whether the job output is believed to be out of date with respect to the input and any other files contained in the project that might be used in the job.

Parameters
verbosityShow information on decision if greater than 0
Returns
true if the output is not up to date, false otherwise

◆ run_verify()

int sjef::Project::run_verify ( int  run) const

Check a run exists, and resolve most recent.

Parameters
runThe run number to check
Returns
run, or the most recent if run was zero. If the requested run is not found, return 0

◆ select_nodes()

pugi::xpath_node_set sjef::Project::select_nodes ( const std::string &  xpath_query,
int  run = 0 
) const

General XPath search on the xml document. Needs the pugixml library to parse the result.

Parameters
xpath_query
run
Returns

◆ set_current_run()

void sjef::Project::set_current_run ( unsigned int  run = 0)

Set the focussed run directory.

Parameters
runThe index of an existing run directory, a positive integer, or zero, indicating that the focus is on the most recent run directory

◆ set_verbosity()

void sjef::Project::set_verbosity ( int  verbosity,
std::ostream &  stream = std::cout 
)
inline

◆ set_warnings()

void sjef::Project::set_warnings ( const Logger::Levels  level = Logger::Levels::warning,
std::ostream &  stream = std::cerr,
std::vector< std::string >  preambles = {"sjef:: Error: ", "sjef:: Warning: ", "sjef:: Note:"} 
)
inline

Set the warning/error diagnostic level and destination.

Parameters
stream
level
preambles

◆ status()

sjef::status sjef::Project::status ( ) const

Obtain the status of the job started by run()

Returns
  • 0 not found
  • 1 running
  • 2 waiting
  • 3 completed
  • 4 unevaluated
  • 5 killed

◆ status_from_output()

sjef::status sjef::Project::status_from_output ( ) const

Obtain the job status, if possible, by examining the output.

Returns
The status. If nothing can be found, returns status()

◆ status_message()

std::string sjef::Project::status_message ( int  verbosity = 0) const
Returns
An informative string about job status

◆ take_run_files()

void sjef::Project::take_run_files ( int  run = 0,
const std::string &  fromname = "",
const std::string &  toname = "" 
) const

Copy files from a run directory to the main project.

Parameters
runSpecifies the run to use as source, with 0 meaning the currently focussed run directory.
fromnameThe file to copy.
tonameThe destination, defaulting to fromname.

◆ wait()

void sjef::Project::wait ( unsigned int  maximum_microseconds = 10000) const

Wait unconditionally for status() to return neither 'waiting' nor 'running'.

Parameters
maximum_microsecondsThe poll interval is successively increased between calls to status() until reaching this value.

◆ xml()

std::string sjef::Project::xml ( int  run = 0,
bool  sync = true 
) const

Get the xml output, completing any open tags if necessary.

Parameters
runIf present, look for the file in a particular run directory. Otherwise it will search in the currently focussed run directory, and if not found, the main directory
syncWhether to force a synchronisation with backend before getting the file contents
Returns

◆ xpath_search()

std::vector<std::string> sjef::Project::xpath_search ( const std::string &  xpath_query,
const std::string &  attribute = "",
int  run = 0 
) const

Simple XPath search on the xml document. For each matching node found, return a string that contains the value of a specified attribute, or if the attribute is omitted, the node contents.

Parameters
xpath_query
attribute
run
Returns

◆ xpath_xml()

std::vector<std::string> sjef::Project::xpath_xml ( const std::string &  xpath_query,
int  run = 0 
) const

Simple XPath search on the xml document. For each matching node found, return a string that contains a complete XML document with the node as root element.

Parameters
xpath_query
run
Returns

Friends And Related Function Documentation

◆ util::Job

friend class util::Job
friend

Member Data Documentation

◆ suffix_keys

const std::vector<std::string> sjef::Project::suffix_keys
static

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