arts_api.cc File Reference

#include "arts_api.h"
#include "agenda_class.h"
#include "arts.h"
#include "auto_md.h"
#include "auto_version.h"
#include "global_data.h"
#include "interactive_workspace.h"
#include "parameters.h"
#include "parser.h"
#include "workspace_ng.h"

Go to the source code of this file.

Functions
Index	get_wsv_id (const char *)
	Get index of WSV. More...
void	copy_output_and_input (ArrayOfIndex &output, ArrayOfIndex &input, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
void	include_path_push (const char *path)
	Add include path. More...
void	include_path_pop ()
	Remove last include path. More...
void	data_path_push (const char *path)
	Add data path. More...
void	data_path_pop ()
	Remove last data path. More...
void	initialize ()
	Initalize ARTS runtime. More...
void	finalize ()
	Finalize ARTS runtime. More...
const char *	get_error ()
	Get most recent error. More...
void	set_basename (const char *name)
	Set the ARTS basename. More...
Agenda *	parse_agenda (const char *filename)
	Parse Controlfile. More...
Agenda *	create_agenda (const char *name)
	Create Agenda. More...
void	agenda_insert_set (InteractiveWorkspace *workspace, Agenda *a, long id, long group_id)
	Insert a set method into an agenda. More...
void	agenda_insert_callback (Agenda *a, void(*f)(InteractiveWorkspace *))
	Insert callback into agenda. More...
void	agenda_add_method (Agenda *a, const long id, unsigned long n_output_args, const long *output_args, unsigned long n_input_args, const long *input_args)
void	agenda_append (Agenda *dst, const Agenda *src)
	Append agendas. More...
void	agenda_clear (Agenda *a)
	Clear Agenda. More...
const char *	execute_agenda (InteractiveWorkspace *workspace, const Agenda *a)
	Execute Agenda. More...
void	destroy_agenda (Agenda *a)
	Destroy Agenda. More...
InteractiveWorkspace *	create_workspace (const Index verbosity, const Index agenda_verbosity)
	Create new workspace. More...
void	destroy_workspace (InteractiveWorkspace *workspace)
	Destroy given workspace. More...
unsigned long	get_number_of_groups ()
	Return number of WSV groups. More...
const char *	get_group_name (int i)
	Get pointer to name of given group. More...
unsigned long	get_number_of_methods ()
	Return number of WSMs. More...
MethodStruct	get_method (Index i)
	Return MethodStruct describing method with index i. More...
const char *	get_method_in (Index i, Index j)
const char *	get_method_g_in (Index i, Index j)
	Get name of generic input argument. More...
const char *	get_method_g_in_default (Index i, Index j)
	Get default value of generic input argument. More...
const char *	get_method_out (Index i, Index j)
const char *	get_method_g_out (Index i, Index j)
	Get name value of generic output argument. More...
const char *	execute_workspace_method (InteractiveWorkspace *workspace, long id, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
	Execute workspace method. More...
const char *	method_print_doc (long id)
	Print method documentation. More...
long	lookup_workspace_variable (const char *s)
	Lookup workspace variable by name. More...
unsigned long	get_number_of_variables ()
	Number of defined WSVs. More...
VariableStruct	get_variable (Index i)
	Get WSV by index. More...
VariableValueStruct	get_variable_value (InteractiveWorkspace *workspace, Index id, Index group_id)
	Get value WSV in given workspace. More...
void *	get_variable_data_pointer (InteractiveWorkspace *workspace, Index id)
	Get data pointer to the WSV variable. More...
CovarianceMatrixBlockStruct	get_covariance_matrix_block (CovarianceMatrix *m, long block_index, bool inverse)
	Return block of covariance matrix. More...
const char *	set_variable_value (InteractiveWorkspace *workspace, long id, long group_id, VariableValueStruct value)
	Sets the value of a WSV in a given workspace. More...
long	add_variable (InteractiveWorkspace *workspace, long group_id, const char *name)
	Add variable of given type to workspace. More...
DLL_PUBLIC void	erase_variable (InteractiveWorkspace *workspace, long id, long group_id)
	Erase variable from workspace. More...
DLL_PUBLIC VersionStruct	get_version ()
	Get ARTS Version. More...

Variables
Parameters	parameters
	Holds the command line parameters. More...
Verbosity	verbosity_at_launch
	The global message verbosity settings: More...
String	out_basename
	The basename for the report file and for all other output files. More...
std::string	string_buffer

Function Documentation

add_variable()

long add_variable	(	InteractiveWorkspace *	workspace,
		long	group_id,
		const char *	name
	)

Add variable of given type to workspace.

This adds and initializes a variable in the current workspace and also adds a new entry to the global wsv_data array and updates WsvMap.

Parameters

workspace	The pointer to the InteractiveWorkspace object where to create the object.
group_id	The index of the group of the variable
name	Pointer to a null-terminated string containing the name of the variable. If nullptr, a name will be auto-generated.

Returns

The index which indentifies the variable in the given workspace.

Definition at line 637 of file arts_api.cc.

References InteractiveWorkspace::add_variable(), and DLL_PUBLIC.

Referenced by InteractiveWorkspace::add_callback(), and get_g_in_nodef().

agenda_add_method()

void agenda_add_method	(	Agenda *	a,
		const long	id,
		unsigned long	n_output_args,
		const long *	output_args,
		unsigned long	n_input_args,
		const long *	input_args
	)

Definition at line 157 of file arts_api.cc.

References copy_output_and_input(), and Agenda::push_back().

agenda_append()

void agenda_append	(	Agenda *	dst,
		const Agenda *	src
	)

Append agendas.

Appends the methods in agenda src to agenda dst. This can be used to emulate include statements in agenda definitions.

Parameters

dst	The agenda to append the methods to
src	The agenda whose methods to append to src

Definition at line 171 of file arts_api.cc.

References Agenda::Methods(), methods(), and Agenda::push_back().

agenda_clear()

void agenda_clear

(

Agenda *

a

)

Clear Agenda.

Resets a given agenda to be emtpy.

Parameters

a	Pointer to agenda object.

Definition at line 178 of file arts_api.cc.

agenda_insert_callback()

void agenda_insert_callback	(	Agenda *	a,
		void(*)(InteractiveWorkspace *)	f
	)

Insert callback into agenda.

Inserts callback to the given function object into the agenda.

Definition at line 149 of file arts_api.cc.

References InteractiveWorkspace::add_callback(), global_data::md_data, and Agenda::push_back().

agenda_insert_set()

void agenda_insert_set	(	InteractiveWorkspace *	ws,
		Agenda *	a,
		long	id,
		long	group_id
	)

Insert a set method into an agenda.

This inserts a set method into the given agenda which sets the a workspace variable given by its ID to to the value it currently has in the given workspace.

Parameters

Pointer	to the workspace
Pointer	to the agenda
Pointer	to the callback function object
Language	type of the callback.

Definition at line 94 of file arts_api.cc.

References global_data::MdMap, Agenda::push_back(), and global_data::wsv_group_names.

copy_output_and_input()

void copy_output_and_input	(	ArrayOfIndex &	output,
		ArrayOfIndex &	input,
		unsigned long	n_args_out,
		const long *	args_out,
		unsigned long	n_args_in,
		const long *	args_in
	)

Definition at line 30 of file arts_api.cc.

References i.

Referenced by agenda_add_method(), and execute_workspace_method().

create_agenda()

Agenda* create_agenda

(

const char *

name

)

Create Agenda.

Creates an empyt agenda.

Parameters

[in]

name

Name of the agenda

Returns

Pointer to the newly created agenda.

Definition at line 88 of file arts_api.cc.

References Agenda::set_name().

create_workspace()

InteractiveWorkspace* create_workspace	(	const Index	verbosity = 1,
		const Index	agenda_verbosity = 0
	)

Create new workspace.

Returns

Pointer to a newly created InteractiveWorkspace object.

Definition at line 191 of file arts_api.cc.

data_path_pop()

void data_path_pop

(

)

Remove last data path.

Remove the most recently added data path. Will result in an exception if the data path is empty.

Definition at line 58 of file arts_api.cc.

References Parameters::datapath.

data_path_push()

void data_path_push

(

const char *

path

)

Add data path.

Adds a given path to the ARTS data path.

Parameters

[in]

path

Pointer to cstring containing the path to add to the data path.

Definition at line 56 of file arts_api.cc.

References Parameters::datapath.

destroy_agenda()

void destroy_agenda

(

Agenda *

a

)

Destroy Agenda.

Parameters

a	Pointer to the agenda.

Definition at line 186 of file arts_api.cc.

destroy_workspace()

void destroy_workspace

(

InteractiveWorkspace *

workspace

)

Destroy given workspace.

Definition at line 196 of file arts_api.cc.

erase_variable()

DLL_PUBLIC void erase_variable	(	InteractiveWorkspace *	workspace,
		long	id,
		long	group_id
	)

Erase variable from workspace.

This variable removes a variable from the workspace and the global wsv_data and WsvMap. This is likely to invalidate indices of existing variables so it should be used with care.

Parameters

workspace	Pointer to the InteractiveWorkspace object owning the variable
id	The index of the variable
group_id	The index of the group of the variable

Definition at line 644 of file arts_api.cc.

References DLL_PUBLIC, and InteractiveWorkspace::erase_variable().

Referenced by InteractiveWorkspace::add_callback(), and get_g_in_nodef().

execute_agenda()

const char* execute_agenda	(	InteractiveWorkspace *	workspace,
		const Agenda *	a
	)

Execute Agenda.

Executes the given agenda on a given workspace.

Parameters

workspace	Pointer of the InteractiveWorkspace object to execute the agenda on.
a	Pointer to the agenda to execute.

Returns

NULL if execution was successfull, otherwise pointer to the c_str holding the error message from ARTS.

Definition at line 180 of file arts_api.cc.

References InteractiveWorkspace::execute_agenda(), and Agenda::set_main_agenda().

execute_workspace_method()

const char* execute_workspace_method	(	InteractiveWorkspace *	workspace,
		long	id,
		unsigned long	n_args_out,
		const long *	args_out,
		unsigned long	n_args_in,
		const long *	args_in
	)

Execute workspace method.

Execute workspace method with given index. Input arguments are passed using pointers to two arrays holding the indices of the input arguments and the output arguments, respectively. The length of the input (output) arguments must of course match the number of non-generic and generic input (output) arguments.

Parameters

i	The index of the WSM
args_out	Pointer to the array holding the indices of the output WSVs.
args_in	Pointer to the array holding the indices of the input WSVs.

Returns

NULL if execution of workspace method was successful, pointer to c_str hodling the ARTS error message otherwise.

Definition at line 262 of file arts_api.cc.

References copy_output_and_input(), and InteractiveWorkspace::execute_workspace_method().

Referenced by get_g_in_nodef().

finalize()

void finalize

(

)

Finalize ARTS runtime.

Deletes the error buffer.

Definition at line 62 of file arts_api.cc.

get_covariance_matrix_block()

CovarianceMatrixBlockStruct get_covariance_matrix_block	(	CovarianceMatrix *	m,
		long	block_index,
		bool	inverse
	)

Return block of covariance matrix.

Parameters

m	Pointer to covariance matrix from which to return the block.
block_index	Index of the block to return.
inverse	Whether the block should be returned from the list of inverse blocks or not.

Returns

Returns the block identified by the given pointer represented by CovarianceMatrixBlockStruct.

Definition at line 467 of file arts_api.cc.

References Block::dense, CovarianceMatrix::get_blocks(), MatrixView::get_c_array(), Sparse::get_column_index_pointer(), Block::get_column_range(), Block::get_dense(), Sparse::get_element_pointer(), Range::get_extent(), Block::get_indices(), CovarianceMatrix::get_inverse_blocks(), Block::get_matrix_type(), Block::get_row_range(), Sparse::get_row_start_pointer(), Block::get_sparse(), Range::get_start(), i, CovarianceMatrixBlockStruct::indices, and Sparse::nnz().

Referenced by get_g_in_nodef().

get_error()

const char* get_error

(

)

Get most recent error.

Returns

Pointer to the c string holding the most recent error message.

Definition at line 66 of file arts_api.cc.

References string_buffer.

get_group_name()

const char* get_group_name

(

int

i

)

Get pointer to name of given group.

Definition at line 204 of file arts_api.cc.

References i, and global_data::wsv_group_names.

get_method()

MethodStruct get_method

(

Index

i

)

Return MethodStruct describing method with index i.

Definition at line 211 of file arts_api.cc.

References i, and global_data::md_data.

get_method_g_in()

const char* get_method_g_in	(	Index	i,
		Index	j
	)

Get name of generic input argument.

Parameters

[in]	i	The index of the WSM
[in]	The	index of the generic input arguments

Returns

Pointer to c_str holding the name of the input argument as defined in methods.cc.

Definition at line 246 of file arts_api.cc.

References i, and global_data::md_data.

get_method_g_in_default()

const char* get_method_g_in_default	(	Index	i,
		Index	j
	)

Get default value of generic input argument.

Parameters

[in]	i	The index of the WSM
[in]	j	The index of the generic input argument

Returns

Pointer to c_str holding the default value as defined in methods.cc.

Definition at line 250 of file arts_api.cc.

References i, and global_data::md_data.

get_method_g_out()

const char* get_method_g_out	(	Index	i,
		Index	j
	)

Get name value of generic output argument.

Parameters

[in]	i	The index of the WSM
[in]	j	The index of the generic output argument

Returns

Pointer to c_str holding the name of the output argument as defined in methods.cc.

Definition at line 258 of file arts_api.cc.

References i, and global_data::md_data.

Referenced by get_g_in_nodef().

get_method_in()

const char* get_method_in	(	Index	i,
		Index	j
	)

Definition at line 242 of file arts_api.cc.

References i, and global_data::md_data.

get_method_out()

const char* get_method_out	(	Index	i,
		Index	j
	)

Definition at line 254 of file arts_api.cc.

References i, and global_data::md_data.

get_number_of_groups()

unsigned long get_number_of_groups

(

)

Return number of WSV groups.

Definition at line 202 of file arts_api.cc.

References global_data::wsv_group_names.

get_number_of_methods()

unsigned long get_number_of_methods

(

)

Return number of WSMs.

Definition at line 209 of file arts_api.cc.

References global_data::md_data.

get_number_of_variables()

unsigned long get_number_of_variables

(

)

Number of defined WSVs.

Definition at line 293 of file arts_api.cc.

References Workspace::wsv_data.

Referenced by get_g_in_nodef().

get_variable()

VariableStruct get_variable

(

Index

i

)

Get WSV by index.

Parameters

The	index of the WSV

Returns

VariableStruct representing the WSV

Definition at line 295 of file arts_api.cc.

References WsvRecord::Description(), WsvRecord::Group(), i, WsvRecord::Name(), r, and Workspace::wsv_data.

Referenced by get_g_in_nodef().

get_variable_data_pointer()

void* get_variable_data_pointer	(	InteractiveWorkspace *	workspace,
		Index	id
	)

Get data pointer to the WSV variable.

Initalize uninitialized WSV variable

Parameters

workspace	Pointer to a InteractiveWorkspace object.
id	Index of the workspace variable.

Returns

void * to the data

Definition at line 463 of file arts_api.cc.

Referenced by get_g_in_nodef().

get_variable_value()

VariableValueStruct get_variable_value	(	InteractiveWorkspace *	workspace,
		Index	id,
		Index	group_id
	)

Get value WSV in given workspace.

Parameters

workspace	Pointer to a InteractiveWorkspace object.
id	Index of the workspace variable.
group_id	Index of the group the variable belongs to.

Returns

VariableValueStruct providing access to the variable.

Definition at line 300 of file arts_api.cc.

References ConstTensor3View::empty(), ConstTensor4View::empty(), ConstTensor5View::empty(), ConstTensor7View::empty(), ConstTensor6View::empty(), ConstVectorView::empty(), ConstMatrixView::empty(), Tensor3View::get_c_array(), Tensor4View::get_c_array(), Tensor5View::get_c_array(), VectorView::get_c_array(), Tensor6View::get_c_array(), MatrixView::get_c_array(), Tensor7View::get_c_array(), Sparse::get_column_index_pointer(), Sparse::get_element_pointer(), Sparse::get_row_start_pointer(), Workspace::is_initialized(), ConstTensor4View::nbooks(), ConstTensor5View::nbooks(), ConstTensor7View::nbooks(), ConstTensor6View::nbooks(), Sparse::ncols(), ConstTensor4View::ncols(), ConstTensor3View::ncols(), ConstTensor5View::ncols(), ConstTensor7View::ncols(), ConstTensor6View::ncols(), ConstMatrixView::ncols(), ConstVectorView::nelem(), ConstTensor7View::nlibraries(), Sparse::nnz(), ConstTensor3View::npages(), ConstTensor4View::npages(), ConstTensor5View::npages(), ConstTensor7View::npages(), ConstTensor6View::npages(), Sparse::nrows(), ConstTensor4View::nrows(), ConstTensor3View::nrows(), ConstTensor5View::nrows(), ConstTensor7View::nrows(), ConstTensor6View::nrows(), ConstMatrixView::nrows(), ConstTensor5View::nshelves(), ConstTensor7View::nshelves(), ConstTensor6View::nshelves(), ConstTensor7View::nvitrines(), ConstTensor6View::nvitrines(), and global_data::wsv_group_names.

Referenced by get_g_in_nodef().

get_version()

DLL_PUBLIC VersionStruct get_version

(

)

Get ARTS Version.

This function returns the ARTS version number as a double precision floating point number.

Returns

The ARTS version.

Definition at line 649 of file arts_api.cc.

References ARTS_FULL_VERSION, VersionStruct::major, VersionStruct::minor, and VersionStruct::revision.

Referenced by get_g_in_nodef().

get_wsv_id()

Index get_wsv_id

(

const char *

name

)

Get index of WSV.

Returns the index the Workspace of the given WSV.

Convenience function which can be called from within the debugger because it takes a plain char pointer instead of a String object as input.

Parameters

[in]

name

WSV name

Returns

Index in Workspace

Author

Oliver Lemke

Definition at line 5771 of file workspace.cc.

include_path_pop()

void include_path_pop

(

)

Remove last include path.

Remove the most recently added include path. Will result in an exception if the include path is empty.

Definition at line 54 of file arts_api.cc.

References Parameters::includepath.

include_path_push()

void include_path_push

(

const char *

path

)

Add include path.

Pushes a given path to the back of the include path.

Parameters

[in]

path

Pointer to cstring containing the path to add to the include path.

Definition at line 50 of file arts_api.cc.

References Parameters::includepath.

initialize()

void initialize

(

)

Initalize ARTS runtime.

This function must be called before any other function to initialize the ARTS C API otherwise bad things will probably happen.

Definition at line 60 of file arts_api.cc.

References InteractiveWorkspace::initialize().

lookup_workspace_variable()

long lookup_workspace_variable

(

const char *

s

)

Lookup workspace variable by name.

Parameters

s	Pointer to c string holding the name of the variable.

Returns

Index of the variable or -1 if no variable with the given name exists.

Definition at line 285 of file arts_api.cc.

References Zeeman::end(), and Workspace::WsvMap.

Referenced by get_g_in_nodef().

method_print_doc()

const char* method_print_doc

(

long

id

)

Print method documentation.

This prints the documentation of the method as it is found for example in the HTML browser to the stream buffer and returns a pointer to it.

Parameters

id	The id of the method.

Returns

Pointer to c string holding the documentation of the method

Definition at line 274 of file arts_api.cc.

References global_data::md_data, and string_buffer.

Referenced by get_g_in_nodef().

parse_agenda()

Agenda* parse_agenda

(

const char *

filename

)

Parse Controlfile.

Parses a controlfile into an Agenda and returns a handle to to this agenda, which can be executed on a workspace using execute_agenda(...).

Note that parsing the same controlfile twice fails if this controlfile creates new WSVs.

Parameters

Definition at line 73 of file arts_api.cc.

References ArtsParser::parse_tasklist(), Agenda::set_main_agenda(), and Agenda::set_name().

set_basename()

void set_basename

(

const char *

name

)

Set the ARTS basename.

The basename is a global variable that is used in some cases by some WSMs for example to store or read data.

Definition at line 68 of file arts_api.cc.

set_variable_value()

const char* set_variable_value	(	InteractiveWorkspace *	workspace,
		long	id,
		long	group_id,
		VariableValueStruct	value
	)

Sets the value of a WSV in a given workspace.

This method can be used to set the value of an ARTS WSV from external data. Currently supported data types are:

• Agenda
• ArrayOfIndex
• ArrayOfString
• Index
• Matrix
• Numeric
• Sparse
• String
• Tensor3, ..., Tensor7
• Vector

For Index and Numeric the data pointer of the VariableValueStruct is assumed to point to the value to set the WSV to. For variables of type String the data pointer is interpreted as pointer to a c_str. For ArrayOfString the data pointer is assumed to point to an array of pointers to c_str. For Vectors and Matrix data is assumed to point an array of double with c-style memory layout and size given by the corresponding values in the dimension field of VariableValueStruct.

Parameters

workspace	Pointer to a InteractiveWorkspace object.
id	Index of the workspace variable.
group_id	Index of the group the variable belongs to.

Returns

Poiter to null-terminated string containing the error message if setting of variable fails.

Definition at line 512 of file arts_api.cc.

References InteractiveWorkspace::initialize_variable(), VariableValueStruct::ptr, InteractiveWorkspace::set_agenda_variable(), and global_data::wsv_group_names.

Referenced by get_g_in_nodef().

Variable Documentation

out_basename

String out_basename

The basename for the report file and for all other output files.

The files will have names like <basename>.rep (for the report file).

Definition at line 42 of file messages.cc.

Referenced by arts_exit(), arts_exit_with_error_message(), filename_ascii(), filename_xml(), filename_xml_with_index(), main(), nca_filename(), and nca_filename_with_index().

parameters

Parameters parameters

Holds the command line parameters.

Definition at line 41 of file parameters.cc.

Referenced by add_basedir(), find_xml_file(), find_xml_file_existence(), main(), open_input_file(), option_methods(), option_workspacevariables(), and ArtsParser::parse_agenda().

string_buffer

std::string string_buffer

Definition at line 22 of file arts_api.cc.

Referenced by InteractiveWorkspace::execute_workspace_method(), get_error(), and method_print_doc().

verbosity_at_launch

Verbosity verbosity_at_launch

The global message verbosity settings:

Definition at line 34 of file messages.cc.

Referenced by main(), set_reporting_level(), and verbosityInit().