Grounding and Solving

Functions to control the grounding and solving process. More...

Modules
	Symbolic Atom Inspection
	Inspection of atoms occurring in ground logic programs.
	Basic Shared Types
	Enumerations shared by various modules.
	Ground Program Inspection
	Functions and data structures to inspect ground programs.
	Ground Program Extension
	Add non-ground program representations (ASTs) to logic programs or extend the ground (aspif) program.
	Model Inspection
	Inspection of models and a high-level interface to add constraints during solving.
	Solving
	Interact with a running search.
	Solver Configuration
	Configuration of search and enumeration algorithms.
	Statistics
	Inspect search and problem stats.
	Theory Propagation
	Extend the search with propagators for arbitrary theories.

Classes
struct	clingo_part
	Struct used to specify the program parts that have to be grounded. More...

Typedefs
typedef struct clingo_control	clingo_control_t
	Control object holding grounding and solving state.
typedef int	clingo_mode_t
	The corresponding type to clingo_mode_e.
typedef struct clingo_part	clingo_part_t
	Struct used to specify the program parts that have to be grounded.
typedef bool(*	clingo_ground_callback_t) (clingo_lib_t *lib, clingo_location_t const *location, char const *name, size_t name_size, clingo_symbol_t const *arguments, size_t arguments_size, void *data, clingo_symbol_callback_t symbol_callback, void *symbol_callback_data)
	Callback function to implement external functions.
typedef struct clingo_const_map	clingo_const_map_t
	A map from constantns to their values.
typedef unsigned	clingo_discard_type_t
	Corresponding type to clingo_discard_type_e.

Enumerations
enum	clingo_mode_e { clingo_mode_parse = 0 , clingo_mode_rewrite = 1 , clingo_mode_ground = 2 , clingo_mode_solve = 3 }
	The available application modes. More...
enum	clingo_discard_type_e { minimize = 1 , project = 2 }
	Enumeration of discardable statements.

Functions
CLINGO_VISIBILITY_DEFAULT bool	clingo_const_map_find (clingo_const_map_t const *map, char const *name, size_t name_size, clingo_symbol_t *symbol, bool *found)
	Get the constant with the given name.
CLINGO_VISIBILITY_DEFAULT bool	clingo_const_map_at (clingo_const_map_t const *map, size_t index, clingo_string_t *name, clingo_symbol_t *symbol)
	Get the name and value of the contstant at the given index.
CLINGO_VISIBILITY_DEFAULT bool	clingo_const_map_size (clingo_const_map_t const *map, size_t *size)
	Get the size of the constant map.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_new (clingo_lib_t *lib, clingo_string_t const *arguments, size_t size, clingo_control_t **control)
	Create a new control object.
CLINGO_VISIBILITY_DEFAULT void	clingo_control_acquire (clingo_control_t *control)
	Increment the reference count of the given control object.
CLINGO_VISIBILITY_DEFAULT void	clingo_control_release (clingo_control_t *control)
	Decrement the reference count of the given control object and destroy if zero.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_mode (clingo_control_t *control, clingo_mode_t *mode)
	Get the configured mode.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_parse_files (clingo_control_t *control, clingo_string_t const *files, size_t size)
	Extend the logic program with a program in a file.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_parse_string (clingo_control_t *control, char const *program, size_t size)
	Extend the logic program with the given non-ground logic program in string form.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_ground (clingo_control_t *control, clingo_part_t const *parts, size_t size, clingo_ground_callback_t ground_callback, void *data)
	Ground the selected parts of the current (non-ground) logic program.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_main (clingo_control_t *control)
	Execute the default ground and solve flow after parsing.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_const_map (clingo_control_t *control, clingo_const_map_t const **map)
	Get the map of constants.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_buffer (clingo_control_t *control, clingo_string_t *result)
	Get the output of the text output.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_get_parts (clingo_control_t *control, clingo_part_t const **parts, size_t *size, bool *has_value)
	Get the program parts to ground.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_set_parts (clingo_control_t *control, clingo_part_t const *parts, size_t size, bool has_value)
	Set the program parts to ground.
CLINGO_VISIBILITY_DEFAULT bool	clingo_control_discard (clingo_control_t *control, clingo_discard_type_t type)
	Discard the statements of the given types.
CLINGO_VISIBILITY_DEFAULT void	clingo_control_interrupt (clingo_control_t *control)
	Interrupt the running search.

Detailed Description

Functions to control the grounding and solving process.

For an example, see control.c.

Typedef Documentation

clingo_ground_callback_t

typedef bool(* clingo_ground_callback_t) (clingo_lib_t *lib, clingo_location_t const *location, char const *name, size_t name_size, clingo_symbol_t const *arguments, size_t arguments_size, void *data, clingo_symbol_callback_t symbol_callback, void *symbol_callback_data)

Callback function to implement external functions.

If an external function of form @name(parameters) occurs in a logic program, then this function is called with its location, name, parameters, and a callback to inject symbols as arguments. The callback can be called multiple times; all symbols passed are injected.

If a (non-recoverable) clingo API function fails in this callback, for example, the symbol callback, the callback must return its return code. In case of errors not related to clingo, this function can use clingo_set_error().

Parameters

[in]	lib	the library object
[in]	location	location from which the external function was called
[in]	name	name of the called external function
[in]	arguments	arguments of the called external function
[in]	arguments_size	number of arguments
[in]	data	user data of the callback
[in]	symbol_callback	function to inject symbols
[in]	symbol_callback_data	user data for the symbol callback (must be passed untouched)

Returns

whether the call was successful

See also

clingo_control_ground()

The following example implements the external function @f() returning 42.

bool
ground_callback(clingo_lib_t *lib,
                clingo_location_t const *location,
                char const *name,
                size_t name_size,
                clingo_symbol_t const *arguments,
                size_t arguments_size,
                void *data,
                clingo_symbol_callback_t symbol_callback,
                void *symbol_callback_data) {
  if (size == 1 && strncmp(name, "f", 1) == 0 && arguments_size == 0) {
    clingo_symbol_t sym;
    sym = clingo_symbol_create_number(42);
    return symbol_callback(&sym, 1, symbol_callback_data);
  }
  return clingo_set_error(lib, clingo_result_runtime, "function not found", 18);
}

clingo_part_t

typedef struct clingo_part clingo_part_t

Struct used to specify the program parts that have to be grounded.

Programs may be structured into parts, which can be grounded independently with clingo_control_ground. Program parts are mainly interesting for incremental grounding and multi-shot solving. For single-shot solving, program parts are not needed.

Note

Parts of a logic program without an explicit #program specification are by default put into a program called base without arguments.

See also

clingo_control_ground()

Enumeration Type Documentation

clingo_mode_e

enum clingo_mode_e

The available application modes.

Enumerator
clingo_mode_parse	parse only
clingo_mode_rewrite	parse and rewrite
clingo_mode_ground	parse, rewrite, ground
clingo_mode_solve	parse, rewrite, ground, and solve

Function Documentation

clingo_const_map_at()

CLINGO_VISIBILITY_DEFAULT bool clingo_const_map_at	(	clingo_const_map_t const *	map,
		size_t	index,
		clingo_string_t *	name,
		clingo_symbol_t *	symbol
	)

Get the name and value of the contstant at the given index.

Parameters

[in]	map	the target
[in]	index	the index of the elemnt
[out]	name	the name of the constant
[out]	symbol	the value of the constant

Returns

wether the call was successful

clingo_const_map_find()

CLINGO_VISIBILITY_DEFAULT bool clingo_const_map_find	(	clingo_const_map_t const *	map,
		char const *	name,
		size_t	name_size,
		clingo_symbol_t *	symbol,
		bool *	found
	)

Get the constant with the given name.

Parameters

[in]	map	the target
[in]	name	the name of the constant
[in]	name_size	the size of the name
[out]	symbol	the value of the constant
[out]	found	whether the constant was found

Returns

wether the call was successful

clingo_const_map_size()

CLINGO_VISIBILITY_DEFAULT bool clingo_const_map_size	(	clingo_const_map_t const *	map,
		size_t *	size
	)

Get the size of the constant map.

Parameters

[in]	map	the target
[out]	size	the size of the map

Returns

wether the call was successful

clingo_control_acquire()

CLINGO_VISIBILITY_DEFAULT void clingo_control_acquire

(

clingo_control_t *

control

)

Increment the reference count of the given control object.

Parameters

[in]

control

the target

clingo_control_buffer()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_buffer	(	clingo_control_t *	control,
		clingo_string_t *	result
	)

Get the output of the text output.

Note

The control object has to be created passing option --text-buffer.

Parameters

[in]	control	the target
[out]	result	the resulting string

Returns

wether the call was successful

clingo_control_const_map()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_const_map	(	clingo_control_t *	control,
		clingo_const_map_t const **	map
	)

Get the map of constants.

Parameters

[in]	control	the target
[out]	map	the map of constants

Returns

wether the call was successful

clingo_control_discard()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_discard	(	clingo_control_t *	control,
		clingo_discard_type_t	type
	)

Discard the statements of the given types.

Parameters

[in]	control	the target control
[in]	type	what to discard

clingo_control_get_parts()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_get_parts	(	clingo_control_t *	control,
		clingo_part_t const **	parts,
		size_t *	size,
		bool *	has_value
	)

Get the program parts to ground.

Parameters

[in]	control	the target
[out]	parts	the resulting parts
[out]	size	the resulting parts
[out]	has_value	the resulting parts

Returns

wether the call was successful

clingo_control_ground()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_ground	(	clingo_control_t *	control,
		clingo_part_t const *	parts,
		size_t	size,
		clingo_ground_callback_t	ground_callback,
		void *	data
	)

Ground the selected parts of the current (non-ground) logic program.

After grounding, logic programs can be solved with clingo_control_solve().

Note

Parts of a logic program without an explicit #program specification are by default put into a program called base without arguments.

Parameters

[in]	control	the target
[in]	parts	array of parts to ground
[in]	size	size of the parts array
[in]	ground_callback	callback to implement external functions
[in]	data	user data for ground_callback

Returns

wether the call was successful

Examples

control.c.

clingo_control_interrupt()

CLINGO_VISIBILITY_DEFAULT void clingo_control_interrupt

(

clingo_control_t *

control

)

Interrupt the running search.

It is generally better to use clingo_solve_handle_cancel(). This function is thread-safe.

Parameters

[in]

control

the target

clingo_control_main()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_main

(

clingo_control_t *

control

)

Execute the default ground and solve flow after parsing.

Parameters

[in]

control

the target

Returns

wether the call was successful

clingo_control_mode()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_mode	(	clingo_control_t *	control,
		clingo_mode_t *	mode
	)

Get the configured mode.

Parameters

[in]	control	the target
[in]	mode	the mode

Returns

wether the call was successful

clingo_control_new()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_new	(	clingo_lib_t *	lib,
		clingo_string_t const *	arguments,
		size_t	size,
		clingo_control_t **	control
	)

Create a new control object.

A control object has to be freed using clingo_control_free().

Note

Only gringo options (without --output) and clasp's options are supported as arguments, except basic options such as --help. Furthermore, a control object is blocked while a search call is active; you must not call any member function during search.

Parameters

[in]	lib	clingo library object
[in]	arguments	string array of command line arguments
[in]	size	size of the arguments array
[out]	control	resulting control object

Returns

wether the call was successful

Examples

control.c.

clingo_control_parse_files()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_parse_files	(	clingo_control_t *	control,
		clingo_string_t const *	files,
		size_t	size
	)

Extend the logic program with a program in a file.

Parameters

[in]	control	the target
[in]	files	the files to parse
[in]	size	the number of files to parse

Returns

wether the call was successful

clingo_control_parse_string()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_parse_string	(	clingo_control_t *	control,
		char const *	program,
		size_t	size
	)

Extend the logic program with the given non-ground logic program in string form.

After extending the logic program, the corresponding program parts are typically grounded with clingo_control_ground.

Parameters

[in]	control	the target
[in]	program	string representation of the program
[in]	size	the size of the program

Returns

wether the call was successful

Examples

control.c.

clingo_control_release()

CLINGO_VISIBILITY_DEFAULT void clingo_control_release

(

clingo_control_t *

control

)

Decrement the reference count of the given control object and destroy if zero.

Parameters

[in]

control

the target

Examples

control.c.

clingo_control_set_parts()

CLINGO_VISIBILITY_DEFAULT bool clingo_control_set_parts	(	clingo_control_t *	control,
		clingo_part_t const *	parts,
		size_t	size,
		bool	has_value
	)

Set the program parts to ground.

Parameters

[in]	control	the target
[in]	parts	the parts to set
[in]	size	the size of the parts
[in]	has_value	whether parts are available

Returns

wether the call was successful