Derived application interface class that spawns a simulation code using a separate process and communicates with it through files. More...

Inheritance diagram for ProcessApplicInterface:

Public Member Functions
	ProcessApplicInterface (const ProblemDescDB &problem_db)
	constructor

	~ProcessApplicInterface ()
	destructor

Public Member Functions inherited from ApplicationInterface
	ApplicationInterface (const ProblemDescDB &problem_db)
	constructor

	~ApplicationInterface ()
	destructor

Public Member Functions inherited from Interface
	Interface ()
	default constructor More...

	Interface (ProblemDescDB &problem_db)
	standard constructor for envelope More...

	Interface (const Interface &interface_in)
	copy constructor More...

virtual	~Interface ()
	destructor

Interface	operator= (const Interface &interface_in)
	assignment operator

virtual int	minimum_points (bool constraint_flag) const
	returns the minimum number of points required to build a particular ApproximationInterface (used by DataFitSurrModels).

virtual int	recommended_points (bool constraint_flag) const
	returns the recommended number of points required to build a particular ApproximationInterface (used by DataFitSurrModels).

virtual void	active_model_key (const Pecos::ActiveKey &key)
	activate an approximation state based on its key

virtual void	clear_model_keys ()
	reset initial state by removing all model keys for an approximation

virtual void	approximation_function_indices (const SizetSet &approx_fn_indices)
	set the (currently active) approximation function index set

virtual void	update_approximation (const Variables &vars, const IntResponsePair &response_pr)
	updates the anchor point for an approximation

virtual void	update_approximation (const RealMatrix &samples, const IntResponseMap &resp_map)
	updates the current data points for an approximation

virtual void	update_approximation (const VariablesArray &vars_array, const IntResponseMap &resp_map)
	updates the current data points for an approximation

virtual void	append_approximation (const Variables &vars, const IntResponsePair &response_pr)
	appends a single point to an existing approximation

virtual void	append_approximation (const RealMatrix &samples, const IntResponseMap &resp_map)
	appends multiple points to an existing approximation

virtual void	append_approximation (const VariablesArray &vars_array, const IntResponseMap &resp_map)
	appends multiple points to an existing approximation

virtual void	append_approximation (const IntVariablesMap &vars_map, const IntResponseMap &resp_map)
	appends multiple points to an existing approximation

virtual void	replace_approximation (const IntResponsePair &response_pr)
	replace the response for a single point within an existing approximation

virtual void	replace_approximation (const IntResponseMap &resp_map)
	replace responses for multiple points within an existing approximation

virtual void	track_evaluation_ids (bool track)
	assigns trackEvalIds to activate tracking of evaluation ids within surrogate data, enabling id-based lookups for data replacement

virtual void	build_approximation (const RealVector &c_l_bnds, const RealVector &c_u_bnds, const IntVector &di_l_bnds, const IntVector &di_u_bnds, const RealVector &dr_l_bnds, const RealVector &dr_u_bnds)
	builds the approximation

virtual void	export_approximation ()
	export the approximation to disk

virtual void	rebuild_approximation (const BitArray &rebuild_fns)
	rebuilds the approximation after a data update

virtual void	pop_approximation (bool save_data)
	removes data from last append from the approximation

virtual void	push_approximation ()
	retrieves approximation data from a previous state (negates pop)

virtual bool	push_available ()
	queries the approximation for the ability to retrieve a previous increment

virtual void	finalize_approximation ()
	finalizes the approximation by applying all trial increments

virtual void	combine_approximation ()
	combine the current approximation with previously stored data sets

virtual void	combined_to_active (bool clear_combined=true)
	promote the combined approximation to the currently active one

virtual void	clear_inactive ()
	clear inactive approximation data

virtual bool	advancement_available ()
	query for available advancements in approximation resolution controls

virtual bool	formulation_updated () const
	query for change in approximation formulation

virtual void	formulation_updated (bool update)
	assign an updated status for approximation formulation to force rebuild

virtual Real2DArray	cv_diagnostics (const StringArray &metric_types, unsigned num_folds)
	approximation cross-validation quality metrics per response function

virtual RealArray	challenge_diagnostics (const String &metric_type, const RealMatrix &challenge_pts)
	approximation challenge data metrics per response function

virtual void	clear_current_active_data ()
	clears current data from an approximation interface

virtual void	clear_active_data ()
	clears all data from an approximation interface

virtual SharedApproxData &	shared_approximation ()
	retrieve the SharedApproxData within an ApproximationInterface

virtual std::vector< Approximation > &	approximations ()
	retrieve the Approximations within an ApproximationInterface

virtual const Pecos::SurrogateData &	approximation_data (size_t fn_index)
	retrieve the approximation data from a particular Approximation within an ApproximationInterface

virtual const RealVectorArray &	approximation_coefficients (bool normalized=false)
	retrieve the approximation coefficients from each Approximation within an ApproximationInterface

virtual void	approximation_coefficients (const RealVectorArray &approx_coeffs, bool normalized=false)
	set the approximation coefficients within each Approximation within an ApproximationInterface

virtual const RealVector &	approximation_variances (const Variables &vars)
	retrieve the approximation variances from each Approximation within an ApproximationInterface

virtual const String2DArray &	analysis_components () const
	retrieve the analysis components, if available

virtual void	discrepancy_emulation_mode (short mode)
	set discrepancy emulation mode used for approximating response differences

IntResponseMap &	response_map ()
	return rawResponseMap

void	cache_unmatched_response (int raw_id)
	migrate an unmatched response record from rawResponseMap to cachedResponseMap

void	cache_unmatched_responses ()
	migrate all remaining response records from rawResponseMap to cachedResponseMap

void	assign_rep (std::shared_ptr< Interface > interface_rep)
	assign letter or replace existing letter with a new one More...

void	assign_rep (Interface *interface_rep, bool ref_count_incr=false)
	assign letter or replace existing letter with a new one DEPRECATED, but left for library mode clients to migrate: transfers memory ownership to the contained shared_ptr; ref_count_incr is ignored More...

unsigned short	interface_type () const
	returns the interface type

const String &	interface_id () const
	returns the interface identifier

int	evaluation_id () const
	returns the value of the (total) evaluation id counter for the interface

void	fine_grained_evaluation_counters (size_t num_fns)
	set fineGrainEvalCounters to true and initialize counters if needed

void	init_evaluation_counters (size_t num_fns)
	initialize fine grained evaluation counters, sizing if needed

void	set_evaluation_reference ()
	set evaluation count reference points for the interface

void	print_evaluation_summary (std::ostream &s, bool minimal_header, bool relative_count) const
	print an evaluation summary for the interface

bool	multi_proc_eval () const
	returns a flag signaling the use of multiprocessor evaluation partitions

bool	iterator_eval_dedicated_master () const
	returns a flag signaling the use of a dedicated master processor at the iterator-evaluation scheduling level

bool	is_null () const
	function to check interfaceRep (does this envelope contain a letter?)

std::shared_ptr< Interface >	interface_rep ()
	function to return the letter

void	eval_tag_prefix (const String &eval_id_str, bool append_iface_id=true)
	set the evaluation tag prefix (does not recurse) More...

Protected Member Functions
void	derived_map (const Variables &vars, const ActiveSet &set, Response &response, int fn_eval_id)
	Called by map() and other functions to execute the simulation in synchronous mode. The portion of performing an evaluation that is specific to a derived class.

void	derived_map_asynch (const ParamResponsePair &pair)
	Called by map() and other functions to execute the simulation in asynchronous mode. The portion of performing an asynchronous evaluation that is specific to a derived class.

void	wait_local_evaluations (PRPQueue &prp_queue)
	For asynchronous function evaluations, this method is used to detect completion of jobs and process their results. It provides the processing code that is specific to derived classes. This version waits for at least one completion.

void	test_local_evaluations (PRPQueue &prp_queue)
	For asynchronous function evaluations, this method is used to detect completion of jobs and process their results. It provides the processing code that is specific to derived classes. This version is nonblocking and will return without any completions if none are immediately available.

const StringArray &	analysis_drivers () const
	retrieve the analysis drivers specification for application interfaces

void	file_cleanup () const

void	file_and_workdir_cleanup (const bfs::path &params_path, const bfs::path &results_path, const bfs::path &workdir_path, const String &tag) const

void	remove_params_results_files (const bfs::path &params_path, const bfs::path &results_path) const
	Remove (potentially autotagged for multiple programs) parameters and results files with passed root names.

void	autotag_files (const bfs::path &params_path, const bfs::path &results_path, const String &eval_id_tag) const
	Utility to automatically tag parameters and results files with passed root names (the files may already need per-program tagging) More...

virtual void	wait_local_evaluation_sequence (PRPQueue &prp_queue)=0
	version of wait_local_evaluations() managing of set of individual asynchronous evaluations

virtual void	test_local_evaluation_sequence (PRPQueue &prp_queue)=0
	version of test_local_evaluations() managing of set of individual asynchronous evaluations

virtual void	map_bookkeeping (pid_t pid, int fn_eval_id)=0
	bookkeeping of process and evaluation ids for asynchronous maps

virtual pid_t	create_evaluation_process (bool block_flag)=0
	Spawn the evaluation by managing the input filter, analysis drivers, and output filter. Called from derived_map() & derived_map_asynch().

void	wait_local_evaluation_batch (PRPQueue &prp_queue)
	batch version of wait_local_evaluations()

void	test_local_evaluation_batch (PRPQueue &prp_queue)
	batch version of test_local_evaluations()

void	synchronous_local_analyses (int start, int end, int step)
	execute analyses synchronously on the local processor More...

void	define_filenames (const String &eval_id_tag)
	define modified filenames from user input by handling Unix temp file and optionally tagging with given eval_id_tag

void	write_parameters_files (const Variables &vars, const ActiveSet &set, const Response &response, const int id)
	write the parameters data and response request data to one or more parameters files (using one or more invocations of write_parameters_file()) in either standard or aprepro format

void	read_results_files (Response &response, const int id, const String &eval_id_tag)
	read the response object from one or more results files using full eval_id_tag passed

bfs::path	get_workdir_name ()
	construct a work directory name (tmp or named), with optional tag

void	prepare_process_environment ()
	set PATH, environment variables, and change directory prior to fork/system/spawn More...

void	reset_process_environment ()
	reset PATH and current directory after system/spawn (workdir case) More...

Protected Member Functions inherited from ApplicationInterface
void	init_communicators (const IntArray &message_lengths, int max_eval_concurrency)
	allocate communicator partitions for concurrent evaluations within an iterator and concurrent multiprocessor analyses within an evaluation.

void	set_communicators (const IntArray &message_lengths, int max_eval_concurrency)
	set the local parallel partition data for an interface (the partitions are already allocated in ParallelLibrary).

void	init_serial ()

int	asynch_local_evaluation_concurrency () const
	return asynchLocalEvalConcurrency

short	interface_synchronization () const
	return interfaceSynchronization

bool	evaluation_cache () const
	return evalCacheFlag

bool	restart_file () const
	return evalCacheFlag

String	final_eval_id_tag (int fn_eval_id)
	form and return the final evaluation ID tag, appending iface ID if needed

void	map (const Variables &vars, const ActiveSet &set, Response &response, bool asynch_flag=false)
	Provides a "mapping" of variables to responses using a simulation. Protected due to Interface letter-envelope idiom. More...

void	manage_failure (const Variables &vars, const ActiveSet &set, Response &response, int failed_eval_id)
	manages a simulation failure using abort/retry/recover/continuation

const IntResponseMap &	synchronize ()
	executes a blocking schedule for asynchronous evaluations in the beforeSynchCorePRPQueue and returns all jobs More...

const IntResponseMap &	synchronize_nowait ()
	executes a nonblocking schedule for asynchronous evaluations in the beforeSynchCorePRPQueue and returns a partial set of completed jobs More...

void	serve_evaluations ()
	run on evaluation servers to serve the iterator master More...

void	stop_evaluation_servers ()
	used by the iterator master to terminate evaluation servers More...

bool	check_multiprocessor_analysis (bool warn)
	checks on multiprocessor analysis configuration

bool	check_asynchronous (bool warn, int max_eval_concurrency)
	checks on asynchronous configuration (for direct interfaces)

bool	check_multiprocessor_asynchronous (bool warn, int max_eval_concurrency)
	checks on asynchronous settings for multiprocessor partitions

String	final_batch_id_tag ()
	form and return the final batch ID tag

virtual void	init_communicators_checks (int max_eval_concurrency)
	perform construct-time error checks on the parallel configuration More...

virtual void	set_communicators_checks (int max_eval_concurrency)
	perform run-time error checks on the parallel configuration More...

void	master_dynamic_schedule_analyses ()
	blocking dynamic schedule of all analyses within a function evaluation using message passing More...

void	serve_analyses_synch ()
	serve the master analysis scheduler and manage one synchronous analysis job at a time More...

virtual int	synchronous_local_analysis (int analysis_id)
	Execute a particular analysis (identified by analysis_id) synchronously on the local processor. Used for the derived class specifics within ApplicationInterface::serve_analyses_synch().

Protected Member Functions inherited from Interface
	Interface (BaseConstructor, const ProblemDescDB &problem_db)
	constructor initializes the base class part of letter classes (BaseConstructor overloading avoids infinite recursion in the derived class constructors - Coplien, p. 139) More...

	Interface (NoDBBaseConstructor, size_t num_fns, short output_level)
	constructor initializes the base class part of letter classes (NoDBBaseConstructor used for on the fly instantiations without a DB)

void	init_algebraic_mappings (const Variables &vars, const Response &response)
	Define algebraicACVIndices, algebraicACVIds, and algebraicFnIndices.

void	asv_mapping (const ActiveSet &total_set, ActiveSet &algebraic_set, ActiveSet &core_set)
	define the evaluation requirements for algebraic_mappings() (algebraic_set) and the core Application/Approximation mapping (core_set) from the total Interface evaluation requirements (total_set)

void	asv_mapping (const ActiveSet &algebraic_set, ActiveSet &total_set)
	map an algebraic ASV back to original total ordering for asynch recovery

void	algebraic_mappings (const Variables &vars, const ActiveSet &algebraic_set, Response &algebraic_response)
	evaluate the algebraic_response using the AMPL solver library and the data extracted from the algebraic_mappings file

void	response_mapping (const Response &algebraic_response, const Response &core_response, Response &total_response)
	combine the response from algebraic_mappings() with the response from derived_map() to create the total response More...

Protected Attributes
bool	fileTagFlag
	flags tagging of parameter/results files

bool	fileSaveFlag
	flags retention of parameter/results files

bool	commandLineArgs
	flag indicating use of passing of filenames as command line arguments to the analysis drivers and input/output filters

bool	apreproFlag
	flag indicating use of the APREPRO (the Sandia "A PRE PROcessor" utility) format for parameter files

unsigned short	resultsFileFormat
	results file format

bool	multipleParamsFiles
	flag indicating the need for separate parameters files for multiple analysis drivers

std::string	iFilterName
	the name of the input filter (input_filter user specification)

std::string	oFilterName
	the name of the output filter (output_filter user specification)

std::vector< String >	programNames
	the names of the analysis code programs (analysis_drivers user specification)

std::string	specifiedParamsFileName
	the name of the parameters file from user specification

std::string	paramsFileName
	the parameters file name actually used (modified with tagging or temp files); only valid from define_filenames to write_parameters_files

std::string	paramsFileWritten
	actual, qualified name of the params file written, possibly with workdir

std::string	specifiedResultsFileName
	the name of the results file from user specification

std::string	resultsFileName
	the results file name actually used (modified with tagging or temp files); only valid from define_filenames to write_parameters_files

std::string	resultsFileWritten
	actual, qualified name of the results file written, possibly with workdir

std::string	fullEvalId
	complete evalIdTag, possibly including hierarchical tagging and final eval id, but not program numbers, for passing to write_parameters_files

bool	allowExistingResults
	by default analysis code interfaces delete results files if they exist; user may override with this flag and we'll try to gather and only fork if needed

std::map< int, PathTriple >	fileNameMap
	Maps function evaluation ID to triples (parameters, results, and workdir) paths used in spawning function evaluations. Workdir will be empty if not created specifically for this eval.

bool	useWorkdir
	whether to use a work_directory

std::string	workDirName
	work_directory name, if specified...

bool	dirTag
	whether to tag the working directory

bool	dirSave
	whether dir_save was specified

bfs::path	curWorkdir
	active working directory for this evaluation; valid only from define_filenames to create_evaluation_process

bfs::path	createdDir
	non-empty if created for this eval; valid only from define_filenames to write_parameters_files

StringArray	linkFiles
	template directory (if specified)

StringArray	copyFiles
	template files (if specified)

bool	templateReplace
	whether to replace existing files

Protected Attributes inherited from ApplicationInterface
ParallelLibrary &	parallelLib
	reference to the ParallelLibrary object used to manage MPI partitions for the concurrent evaluations and concurrent analyses parallelism levels

bool	batchEval
	flag indicating usage of batch evaluation facilities, where a set of jobs is launched and scheduled as a unit rather than individually

bool	asynchFlag
	flag indicating usage of asynchronous evaluation

int	batchIdCntr
	maintain a count of the batches

bool	suppressOutput
	flag for suppressing output on slave processors

int	evalCommSize
	size of evalComm

int	evalCommRank
	processor rank within evalComm

int	evalServerId
	evaluation server identifier

bool	eaDedMasterFlag
	flag for dedicated master partitioning at ea level

int	analysisCommSize
	size of analysisComm

int	analysisCommRank
	processor rank within analysisComm

int	analysisServerId
	analysis server identifier

int	numAnalysisServers
	current number of analysis servers

bool	multiProcAnalysisFlag
	flag for multiprocessor analysis partitions

bool	asynchLocalAnalysisFlag
	flag for asynchronous local parallelism of analyses

int	asynchLocalAnalysisConcurrency
	limits the number of concurrent analyses in asynchronous local scheduling and specifies hybrid concurrency when message passing

int	asynchLocalEvalConcSpec
	user specification for asynchronous local evaluation concurrency

int	asynchLocalAnalysisConcSpec
	user specification for asynchronous local analysis concurrency

int	numAnalysisDrivers
	the number of analysis drivers used for each function evaluation (from the analysis_drivers interface specification)

IntSet	completionSet
	the set of completed fn_eval_id's populated by wait_local_evaluations() and test_local_evaluations()

String	failureMessage
	base message for managing failed evals; will be followed with more details in screen output

Protected Attributes inherited from Interface
unsigned short	interfaceType
	the interface type: enum for system, fork, direct, grid, or approximation

String	interfaceId
	the interface specification identifier string from the DAKOTA input file

bool	algebraicMappings
	flag for the presence of algebraic_mappings that define the subset of an Interface's parameter to response mapping that is explicit and algebraic.

bool	coreMappings
	flag for the presence of non-algebraic mappings that define the core of an Interface's parameter to response mapping (using analysis_drivers for ApplicationInterface or functionSurfaces for ApproximationInterface).

short	outputLevel
	output verbosity level: {SILENT,QUIET,NORMAL,VERBOSE,DEBUG}_OUTPUT

int	currEvalId
	identifier for the current evaluation, which may differ from the evaluation counters in the case of evaluation scheduling; used on iterator master as well as server processors. Currently, this is set prior to all invocations of derived_map() for all processors.

bool	fineGrainEvalCounters
	controls use of fn val/grad/hess counters for detailed evaluation report

int	evalIdCntr
	total interface evaluation counter

int	newEvalIdCntr
	new (non-duplicate) interface evaluation counter

int	evalIdRefPt
	iteration reference point for evalIdCntr

int	newEvalIdRefPt
	iteration reference point for newEvalIdCntr

IntArray	fnValCounter
	number of value evaluations by resp fn

IntArray	fnGradCounter
	number of gradient evaluations by resp fn

IntArray	fnHessCounter
	number of Hessian evaluations by resp fn

IntArray	newFnValCounter
	number of new value evaluations by resp fn

IntArray	newFnGradCounter
	number of new gradient evaluations by resp fn

IntArray	newFnHessCounter
	number of new Hessian evaluations by resp fn

IntArray	fnValRefPt
	iteration reference point for fnValCounter

IntArray	fnGradRefPt
	iteration reference point for fnGradCounter

IntArray	fnHessRefPt
	iteration reference point for fnHessCounter

IntArray	newFnValRefPt
	iteration reference point for newFnValCounter

IntArray	newFnGradRefPt
	iteration reference point for newFnGradCounter

IntArray	newFnHessRefPt
	iteration reference point for newFnHessCounter

IntResponseMap	rawResponseMap
	Set of responses returned by either a blocking or nonblocking schedule. More...

IntResponseMap	cachedResponseMap
	Set of available asynchronous responses completed within a blocking or nonblocking scheduler that cannot be processed in a higher level context and need to be stored for later.

StringArray	fnLabels
	response function descriptors (used in print_evaluation_summary() and derived direct interface classes); initialized in map() functions due to potential updates after construction

bool	multiProcEvalFlag
	flag for multiprocessor evaluation partitions (evalComm)

bool	ieDedMasterFlag
	flag for dedicated master partitioning at the iterator level

String	evalTagPrefix
	set of period-delimited evaluation ID tags to use in evaluation tagging

bool	appendIfaceId
	whether to append the interface ID to the prefix during map (default true)

String2DArray	analysisComponents
	Analysis components for interface types that support them.

Private Member Functions
void	write_parameters_file (const Variables &vars, const ActiveSet &set, const Response &response, const std::string &prog, const std::vector< String > &an_comps, const std::string &params_fname, const bool file_mode_out=true)
	write the variables, active set vector, derivative variables vector, and analysis components to the specified parameters file in either standard or aprepro format

void	read_results_file (Response &response, const bfs::path &path, const int id)
	Open and read the results file at path, properly handling errors. More...

Detailed Description

Derived application interface class that spawns a simulation code using a separate process and communicates with it through files.

ProcessApplicInterface is subclassed for process handles or file completion testing.

Member Function Documentation

◆ file_cleanup()

void file_cleanup ( ) const

protectedvirtual

Remove any files and directories still referenced in the fileNameMap

Reimplemented from Interface.

References WorkdirHelper::concat_path(), ProcessApplicInterface::dirSave, ProcessApplicInterface::fileNameMap, ProcessApplicInterface::fileSaveFlag, ProcessApplicInterface::iFilterName, ProcessApplicInterface::multipleParamsFiles, ProcessApplicInterface::programNames, and WorkdirHelper::recursive_remove().

◆ autotag_files()

void autotag_files	(	const bfs::path &	params_path,
		const bfs::path &	results_path,
		const String &	eval_id_tag
	)		const

protected

Utility to automatically tag parameters and results files with passed root names (the files may already need per-program tagging)

Move specified params and results files to unique tagged versions when needed

References WorkdirHelper::concat_path(), ProcessApplicInterface::iFilterName, ProcessApplicInterface::multipleParamsFiles, ProcessApplicInterface::oFilterName, Interface::outputLevel, ProcessApplicInterface::programNames, WorkdirHelper::rename(), ProcessApplicInterface::specifiedParamsFileName, ProcessApplicInterface::specifiedResultsFileName, and ApplicationInterface::suppressOutput.

◆ synchronous_local_analyses()

void synchronous_local_analyses	(	int	start,
		int	end,
		int	step
	)

inlineprotected

execute analyses synchronously on the local processor

Execute analyses synchronously in succession on the local processor (start to end in step increments). Modeled after ApplicationInterface::synchronous_local_evaluations().

References ApplicationInterface::synchronous_local_analysis().

Referenced by ProcessHandleApplicInterface::create_evaluation_process().

◆ prepare_process_environment()

void prepare_process_environment ( )

protected

set PATH, environment variables, and change directory prior to fork/system/spawn

Guidance: environment (PATH, current directory) should be set immediately before Dakota spawns a process and reset immediately afterwards (except fork which never returns)

References WorkdirHelper::change_directory(), ProcessApplicInterface::curWorkdir, Interface::outputLevel, ProcessApplicInterface::paramsFileName, ProcessApplicInterface::resultsFileName, WorkdirHelper::set_environment(), WorkdirHelper::set_preferred_path(), and ProcessApplicInterface::useWorkdir.

Referenced by ForkApplicInterface::create_analysis_process(), SpawnApplicInterface::create_analysis_process(), SysCallApplicInterface::spawn_analysis_to_shell(), SysCallApplicInterface::spawn_evaluation_to_shell(), SysCallApplicInterface::spawn_input_filter_to_shell(), and SysCallApplicInterface::spawn_output_filter_to_shell().