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

#include <sjef.h>

Public Types

using run_list_t = std::set< int, std::greater< int > >
 Obtain the list of run numbers in reverse order, ie the most recent first. More...
 

Public Member Functions

 Project (const std::string &filename, bool construct=true, const std::string &default_suffix="", const std::map< std::string, std::string > &suffixes={{"inp", "inp"}, {"out", "out"}, {"xml", "xml"}}, const Project *masterProject=nullptr)
 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::string &destination_filename, bool force=false, bool keep_hash=false, bool slave=false)
 Copy the project to another location. More...
 
bool move (const std::string &destination_filename, bool force=false)
 Move the project to another location. More...
 
bool import_file (std::string 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 (std::string 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)
 
bool synchronize (int verbosity=0, bool nostatus=false, bool force=false) const
 Synchronize the project with a cached copy belonging to a backend. name.inp, name.xyz, Info.plist, and any files brought in with import(), will be pushed from the master copy to the backend, and all other files will be pulled from the backend. More...
 
bool run (int verbosity=0, bool force=false, bool wait=false)
 Start a sjef job. More...
 
bool run (std::string name, int verbosity=0, bool force=false, bool wait=false)
 
sjef::status status (int verbosity=0, bool cached=true) 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 ()
 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...
 
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 (bool oldOutput=true, bool output=false, bool unused=false)
 Remove potentially unwanted files from the project. More...
 
void property_set (const std::string &property, const std::string &value)
 Set a property. More...
 
void property_set (const std::map< std::string, std::string > &properties)
 Set one or more properties. More...
 
std::string property_get (const std::string &property) const
 Get the value of a property. More...
 
std::map< std::string, std::string > 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::string 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 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
 
int 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...
 
int run_directory_next () const
 Obtain the sequence number of the next run directory to be created. More...
 
std::string name () const
 
int recent_find (const std::string &filename) const
 
std::string recent (int number=1) const
 
void ensure_remote_server () const
 
void change_backend (std::string backend=std::string{""}, bool force=false)
 Change the active backend. More...
 
std::string propertyFile () const
 
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...
 
std::map< std::string, std::string > 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 std::map< std::string, std::string > &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...
 

Static Public Member Functions

static void erase (const std::string &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::string &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...
 

Public Attributes

std::map< std::string, Backend > m_backends
 

Static Public Attributes

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

Member Typedef Documentation

◆ run_list_t

using sjef::Project::run_list_t = std::set<int, std::greater<int> >

Obtain the list of run numbers in reverse order, ie the most recent first.

Returns

Constructor & Destructor Documentation

◆ Project() [1/3]

sjef::Project::Project ( const std::string &  filename,
bool  construct = true,
const std::string &  default_suffix = "",
const std::map< std::string, std::string > &  suffixes = {{"inp", "inp"}, {"out", "out"}, {"xml", "xml"}},
const Project masterProject = nullptr 
)
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
masterProjectFor internal use only

◆ 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 std::map< std::string, std::string > &  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_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()

std::map<std::string, std::string> 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.

◆ 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 ( bool  oldOutput = true,
bool  output = false,
bool  unused = false 
)

Remove potentially unwanted files from the project.

Parameters
oldOutputWhether to remove old output files
outputWhether to remove all output files
unusedWhether to remove unused files

◆ copy()

bool sjef::Project::copy ( const std::string &  destination_filename,
bool  force = false,
bool  keep_hash = false,
bool  slave = false 
)

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
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.

◆ ensure_remote_server()

void sjef::Project::ensure_remote_server ( ) const

◆ erase()

static void sjef::Project::erase ( const std::string &  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::vector< std::string > &  files,
bool  overwrite = false 
)
inline

◆ export_file() [2/2]

bool sjef::Project::export_file ( std::string  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.

◆ 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::string 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.
Returns
the fully-qualified name of the file

◆ import_file() [1/2]

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

◆ import_file() [2/2]

bool sjef::Project::import_file ( std::string  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.

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

Kill the job started by run()

Returns

◆ move()

bool sjef::Project::move ( const std::string &  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]

std::map<std::string, std::string> 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 std::map< std::string, std::string > &  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::string 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::string &  filename) const

◆ recent_find() [2/2]

static int sjef::Project::recent_find ( const std::string &  suffix,
const std::string &  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 ( int  verbosity = 0,
bool  force = false,
bool  wait = false 
)

Start a sjef job.

Parameters
nameThe name of the backend
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
Returns

◆ run() [2/2]

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

◆ run_delete()

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

Delete a run directory.

Parameters
run

◆ run_directory()

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

Obtain the path of a run directory.

Parameters
run
  • 0: the currently focussed run directory
  • other: the specified run directory
Returns
the fully-qualified name of the directory

◆ run_directory_new()

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

int sjef::Project::run_directory_next ( ) const

Obtain the sequence number of the next run directory to be created.

Returns

◆ 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

◆ 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

◆ status()

sjef::status sjef::Project::status ( int  verbosity = 0,
bool  cached = true 
) const

Obtain the status of the job started by run()

Parameters
verbosity
  • 0 print nothing
  • 1 show result from underlying status commands
cachedIf true, don't actually get status, but instead use the last cached value. initiate the request and return immediately; a subsequent call with wait=true will complete
Returns
  • 0 not found
  • 1 running
  • 2 waiting
  • 3 completed
  • 4 unevaluated
  • 5 killed

◆ status_message()

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

◆ synchronize()

bool sjef::Project::synchronize ( int  verbosity = 0,
bool  nostatus = false,
bool  force = false 
) const

Synchronize the project with a cached copy belonging to a backend. name.inp, name.xyz, Info.plist, and any files brought in with import(), will be pushed from the master copy to the backend, and all other files will be pulled from the backend.

Parameters
verbosityIf >0, show underlying processing
forceIf true, always do the sync
Returns

◆ 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

Member Data Documentation

◆ m_backends

std::map<std::string, Backend> sjef::Project::m_backends

◆ suffix_keys

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

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