Clingo C API
C API for clingo providing high level functions to control grounding and solving.
|
Functions to control the grounding and solving process.
For an example, see control.c.
Modules | |
Symbolic Atom Inspection | |
Inspection of atoms occurring in ground logic programs. | |
Theory Atom Inspection | |
Inspection of theory atoms occurring in ground logic programs. | |
Theory Propagation | |
Extend the search with propagators for arbitrary theories. | |
Program Building | |
Add non-ground program representations (ASTs) to logic programs or extend the ground (aspif) program. | |
Solver Configuration | |
Configuration of search and enumeration algorithms. | |
Statistics | |
Inspect search and problem statistics. | |
Model Inspection | |
Inspection of models and a high-level interface to add constraints during solving. | |
Solving | |
Interact with a running search. | |
Program Inspection | |
Functions and data structures to inspect programs. | |
Classes | |
struct | clingo_part |
Struct used to specify the program parts that have to be grounded. More... | |
Typedefs | |
typedef struct clingo_part | clingo_part_t |
Struct used to specify the program parts that have to be grounded. More... | |
typedef bool(* | clingo_ground_callback_t) (clingo_location_t const *location, char const *name, 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. More... | |
typedef struct clingo_control | clingo_control_t |
Control object holding grounding and solving state. | |
typedef unsigned | clingo_solve_result_bitset_t |
Corresponding type to clingo_solve_result_e. More... | |
Enumerations | |
enum | clingo_solve_result_e { clingo_solve_result_satisfiable = 1, clingo_solve_result_unsatisfiable = 2, clingo_solve_result_exhausted = 4, clingo_solve_result_interrupted = 8 } |
Enumeration of bit masks for solve call results. More... | |
Functions | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_new (char const *const *arguments, size_t arguments_size, clingo_logger_t logger, void *logger_data, unsigned message_limit, clingo_control_t **control) |
Create a new control object. More... | |
CLINGO_VISIBILITY_DEFAULT void | clingo_control_free (clingo_control_t *control) |
Free a control object created with clingo_control_new(). More... | |
Grounding Functions | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_load (clingo_control_t *control, char const *file) |
Extend the logic program with a program in a file. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_add (clingo_control_t *control, char const *name, char const *const *parameters, size_t parameters_size, char const *program) |
Extend the logic program with the given non-ground logic program in string form. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_ground (clingo_control_t *control, clingo_part_t const *parts, size_t parts_size, clingo_ground_callback_t ground_callback, void *ground_callback_data) |
Ground the selected parts of the current (non-ground) logic program. More... | |
Solving Functions | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_solve (clingo_control_t *control, clingo_solve_mode_bitset_t mode, clingo_literal_t const *assumptions, size_t assumptions_size, clingo_solve_event_callback_t notify, void *data, clingo_solve_handle_t **handle) |
Solve the currently grounded logic program enumerating its models. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_cleanup (clingo_control_t *control) |
Clean up the domains of the grounding component using the solving component's top level assignment. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_assign_external (clingo_control_t *control, clingo_literal_t literal, clingo_truth_value_t value) |
Assign a truth value to an external atom. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_release_external (clingo_control_t *control, clingo_literal_t literal) |
Release an external atom. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_register_propagator (clingo_control_t *control, clingo_propagator_t const *propagator, void *data, bool sequential) |
Register a custom propagator with the control object. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_is_conflicting (clingo_control_t const *control) |
Check if the solver has determined that the internal program representation is conflicting. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_statistics (clingo_control_t const *control, clingo_statistics_t const **statistics) |
Get a statistics object to inspect solver statistics. More... | |
CLINGO_VISIBILITY_DEFAULT void | clingo_control_interrupt (clingo_control_t *control) |
Interrupt the active solve call (or the following solve call right at the beginning). More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_clasp_facade (clingo_control_t *control, void **clasp) |
Get low-level access to clasp. More... | |
Configuration Functions | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_configuration (clingo_control_t *control, clingo_configuration_t **configuration) |
Get a configuration object to change the solver configuration. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_set_enable_enumeration_assumption (clingo_control_t *control, bool enable) |
Configure how learnt constraints are handled during enumeration. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_get_enable_enumeration_assumption (clingo_control_t *control) |
Check whether the enumeration assumption is enabled. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_set_enable_cleanup (clingo_control_t *control, bool enable) |
Enable automatic cleanup after solving. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_get_enable_cleanup (clingo_control_t *control) |
Check whether automatic cleanup is enabled. More... | |
Program Inspection Functions | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_get_const (clingo_control_t const *control, char const *name, clingo_symbol_t *symbol) |
Return the symbol for a constant definition of form: #const name = symbol . More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_has_const (clingo_control_t const *control, char const *name, bool *exists) |
Check if there is a constant definition for the given constant. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_symbolic_atoms (clingo_control_t const *control, clingo_symbolic_atoms_t const **atoms) |
Get an object to inspect symbolic atoms (the relevant Herbrand base) used for grounding. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_theory_atoms (clingo_control_t const *control, clingo_theory_atoms_t const **atoms) |
Get an object to inspect theory atoms that occur in the grounding. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_register_observer (clingo_control_t *control, clingo_ground_program_observer_t const *observer, bool replace, void *data) |
Register a program observer with the control object. More... | |
Program Modification Functions | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_backend (clingo_control_t *control, clingo_backend_t **backend) |
Get an object to add ground directives to the program. More... | |
CLINGO_VISIBILITY_DEFAULT bool | clingo_control_program_builder (clingo_control_t *control, clingo_program_builder_t **builder) |
Get an object to add non-ground directives to the program. More... | |
typedef bool(* clingo_ground_callback_t) (clingo_location_t const *location, char const *name, 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 false. In case of errors not related to clingo, this function can set error clingo_error_unknown and return false to stop grounding with an error.
[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) |
The following example implements the external function @f()
returning 42.
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.
#program
specification are by default put into a program called base
without arguments.Corresponding type to clingo_solve_result_e.
Enumeration of bit masks for solve call results.
Enumerator | |
---|---|
clingo_solve_result_satisfiable | The last solve call found a solution. |
clingo_solve_result_unsatisfiable | The last solve call did not find a solution. |
clingo_solve_result_exhausted | The last solve call completely exhausted the search space. |
clingo_solve_result_interrupted | The last solve call was interrupted.
|
CLINGO_VISIBILITY_DEFAULT bool clingo_control_add | ( | clingo_control_t * | control, |
char const * | name, | ||
char const *const * | parameters, | ||
size_t | parameters_size, | ||
char const * | program | ||
) |
Extend the logic program with the given non-ground logic program in string form.
This function puts the given program into a block of form: #program name(parameters).
After extending the logic program, the corresponding program parts are typically grounded with clingo_control_ground.
[in] | control | the target |
[in] | name | name of the program block |
[in] | parameters | string array of parameters of the program block |
[in] | parameters_size | number of parameters |
[in] | program | string representation of the program |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_assign_external | ( | clingo_control_t * | control, |
clingo_literal_t | literal, | ||
clingo_truth_value_t | value | ||
) |
Assign a truth value to an external atom.
If a negative literal is passed, the corresponding atom is assigned the inverted truth value.
If the atom does not exist or is not external, this is a noop.
[in] | control | the target |
[in] | literal | literal to assign |
[in] | value | the truth value |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_backend | ( | clingo_control_t * | control, |
clingo_backend_t ** | backend | ||
) |
Get an object to add ground directives to the program.
See the Program Building module for more information.
[in] | control | the target |
[out] | backend | the backend object |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_clasp_facade | ( | clingo_control_t * | control, |
void ** | clasp | ||
) |
Get low-level access to clasp.
This function may return a nullptr
. Otherwise, the returned pointer can be casted to a ClaspFacade pointer.
[in] | control | the target |
[out] | clasp | pointer to the ClaspFacade object (may be nullptr ) |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_cleanup | ( | clingo_control_t * | control | ) |
Clean up the domains of the grounding component using the solving component's top level assignment.
This function removes atoms from domains that are false and marks atoms as facts that are true. With multi-shot solving, this can result in smaller groundings because less rules have to be instantiated and more simplifications can be applied.
[in] | control | the target |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_configuration | ( | clingo_control_t * | control, |
clingo_configuration_t ** | configuration | ||
) |
Get a configuration object to change the solver configuration.
See the Solver Configuration module for more information.
[in] | control | the target |
[out] | configuration | the configuration object |
CLINGO_VISIBILITY_DEFAULT void clingo_control_free | ( | clingo_control_t * | control | ) |
Free a control object created with clingo_control_new().
[in] | control | the target |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_get_const | ( | clingo_control_t const * | control, |
char const * | name, | ||
clingo_symbol_t * | symbol | ||
) |
Return the symbol for a constant definition of form: #const name = symbol
.
[in] | control | the target |
[in] | name | the name of the constant |
[out] | symbol | the resulting symbol |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_get_enable_cleanup | ( | clingo_control_t * | control | ) |
Check whether automatic cleanup is enabled.
See clingo_control_set_enable_cleanup().
[in] | control | the target |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_get_enable_enumeration_assumption | ( | clingo_control_t * | control | ) |
Check whether the enumeration assumption is enabled.
See clingo_control_set_enable_enumeration_assumption().
[in] | control | the target |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_ground | ( | clingo_control_t * | control, |
clingo_part_t const * | parts, | ||
size_t | parts_size, | ||
clingo_ground_callback_t | ground_callback, | ||
void * | ground_callback_data | ||
) |
Ground the selected parts of the current (non-ground) logic program.
After grounding, logic programs can be solved with clingo_control_solve().
#program
specification are by default put into a program called base
without arguments.[in] | control | the target |
[in] | parts | array of parts to ground |
[in] | parts_size | size of the parts array |
[in] | ground_callback | callback to implement external functions |
[in] | ground_callback_data | user data for ground_callback |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_has_const | ( | clingo_control_t const * | control, |
char const * | name, | ||
bool * | exists | ||
) |
Check if there is a constant definition for the given constant.
[in] | control | the target |
[in] | name | the name of the constant |
[out] | exists | whether a matching constant definition exists |
CLINGO_VISIBILITY_DEFAULT void clingo_control_interrupt | ( | clingo_control_t * | control | ) |
Interrupt the active solve call (or the following solve call right at the beginning).
[in] | control | the target |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_is_conflicting | ( | clingo_control_t const * | control | ) |
Check if the solver has determined that the internal program representation is conflicting.
If this function returns true, solve calls will return immediately with an unsatisfiable solve result. Note that conflicts first have to be detected, e.g. - initial unit propagation results in an empty clause, or later if an empty clause is resolved during solving. Hence, the function might return false even if the problem is unsatisfiable.
[in] | control | the target |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_load | ( | clingo_control_t * | control, |
char const * | file | ||
) |
Extend the logic program with a program in a file.
[in] | control | the target |
[in] | file | path to the file |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_new | ( | char const *const * | arguments, |
size_t | arguments_size, | ||
clingo_logger_t | logger, | ||
void * | logger_data, | ||
unsigned | message_limit, | ||
clingo_control_t ** | control | ||
) |
Create a new control object.
A control object has to be freed using clingo_control_free().
--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.If the logger is NULL, messages are printed to stderr.
[in] | arguments | C string array of command line arguments |
[in] | arguments_size | size of the arguments array |
[in] | logger | callback functions for warnings and info messages |
[in] | logger_data | user data for the logger callback |
[in] | message_limit | maximum number of times the logger callback is called |
[out] | control | resulting control object |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_program_builder | ( | clingo_control_t * | control, |
clingo_program_builder_t ** | builder | ||
) |
Get an object to add non-ground directives to the program.
See the Program Building module for more information.
[in] | control | the target |
[out] | builder | the program builder object |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_register_observer | ( | clingo_control_t * | control, |
clingo_ground_program_observer_t const * | observer, | ||
bool | replace, | ||
void * | data | ||
) |
Register a program observer with the control object.
[in] | control | the target |
[in] | observer | the observer to register |
[in] | replace | just pass the grounding to the observer but not the solver |
[in] | data | user data passed to the observer functions |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_register_propagator | ( | clingo_control_t * | control, |
clingo_propagator_t const * | propagator, | ||
void * | data, | ||
bool | sequential | ||
) |
Register a custom propagator with the control object.
If the sequential flag is set to true, the propagator is called sequentially when solving with multiple threads.
See the Theory Propagation module for more information.
[in] | control | the target |
[in] | propagator | the propagator |
[in] | data | user data passed to the propagator functions |
[in] | sequential | whether the propagator should be called sequentially |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_release_external | ( | clingo_control_t * | control, |
clingo_literal_t | literal | ||
) |
Release an external atom.
If a negative literal is passed, the corresponding atom is released.
After this call, an external atom is no longer external and subject to program simplifications. If the atom does not exist or is not external, this is a noop.
[in] | control | the target |
[in] | literal | literal to release |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_set_enable_cleanup | ( | clingo_control_t * | control, |
bool | enable | ||
) |
Enable automatic cleanup after solving.
[in] | control | the target |
[in] | enable | whether to enable cleanups |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_set_enable_enumeration_assumption | ( | clingo_control_t * | control, |
bool | enable | ||
) |
Configure how learnt constraints are handled during enumeration.
If the enumeration assumption is enabled, then all information learnt from the solver's various enumeration modes is removed after a solve call. This includes enumeration of cautious or brave consequences, enumeration of answer sets with or without projection, or finding optimal models, as well as clauses added with clingo_solve_control_add_clause().
[in] | control | the target |
[in] | enable | whether to enable the assumption |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_solve | ( | clingo_control_t * | control, |
clingo_solve_mode_bitset_t | mode, | ||
clingo_literal_t const * | assumptions, | ||
size_t | assumptions_size, | ||
clingo_solve_event_callback_t | notify, | ||
void * | data, | ||
clingo_solve_handle_t ** | handle | ||
) |
Solve the currently grounded logic program enumerating its models.
See the Solving module for more information.
[in] | control | the target |
[in] | mode | configures the search mode |
[in] | assumptions | array of assumptions to solve under |
[in] | assumptions_size | number of assumptions |
[in] | notify | the event handler to register |
[in] | data | the user data for the event handler |
[out] | handle | handle to the current search to enumerate models |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_statistics | ( | clingo_control_t const * | control, |
clingo_statistics_t const ** | statistics | ||
) |
Get a statistics object to inspect solver statistics.
Statistics are updated after a solve call.
See the Statistics module for more information.
[in] | control | the target |
[out] | statistics | the statistics object |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_symbolic_atoms | ( | clingo_control_t const * | control, |
clingo_symbolic_atoms_t const ** | atoms | ||
) |
Get an object to inspect symbolic atoms (the relevant Herbrand base) used for grounding.
See the Symbolic Atom Inspection module for more information.
[in] | control | the target |
[out] | atoms | the symbolic atoms object |
CLINGO_VISIBILITY_DEFAULT bool clingo_control_theory_atoms | ( | clingo_control_t const * | control, |
clingo_theory_atoms_t const ** | atoms | ||
) |
Get an object to inspect theory atoms that occur in the grounding.
See the Theory Atom Inspection module for more information.
[in] | control | the target |
[out] | atoms | the theory atoms object |