diogo
/
yap-6.3
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs

This commit is contained in:
Vitor Santos Costa 2018-11-29 13:56:06 +00:00
parent 000c9c0968
commit 6372151bf1
7 changed files with 480 additions and 1022 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/CMakeLists.txt
View File

@ -31,13 +31,13 @@ SET( EXT
string(APPEND CMAKE_HTML_EXTRA ${i} " ")
endforeach(i ${CMAKE_HTML_EXTRA_})
set(DOCS_EXCLUDE_
set(DOC_DIRS_EXCLUDE_
${CMAKE_SOURCE_DIR}/build
${CMAKE_SOURCE_DIR}/Debug
${CMAKE_SOURCE_DIR}/packages/jpl
${CMAKE_SOURCE_DIR}/packages/swig
${CMAKE_SOURCE_DIR}/packages/Problog/problog_examples/output
${CMAKE_SOURCE_DIR}/packages/Problog/problog_examples/queries
${CMAKE_SOURCE_DIR}/packages/swi
${CMAKE_SOURCE_DIR}/packages/Problog/problog_examples
${CMAKE_SOURCE_DIR}/packages/myddas/sqlite3/src
${CMAKE_SOURCE_DIR}/packages/gecode/6.0.1
${CMAKE_SOURCE_DIR}/packages/gecode/6.0.0
@ -52,13 +52,7 @@ ${CMAKE_SOURCE_DIR}/packages/gecode/3.7.2
${CMAKE_SOURCE_DIR}/packages/gecode/3.7.1
${CMAKE_SOURCE_DIR}/packages/gecode/3.7.0
${CMAKE_SOURCE_DIR}/packages/gecode/3.6.0
${CMAKE_SOURCE_DIR}/packages/problog
${CMAKE_SOURCE_DIR}/packages/gecode/dev
${CMAKE_SOURCE_DIR}/C/traced_absmi_insts.h
${CMAKE_SOURCE_DIR}/H/globals.h
${CMAKE_SOURCE_DIR}/OPTYap/locks_alpha_funcs.h
${CMAKE_SOURCE_DIR}/OPTYap/locks_mips_funcs.h
${CMAKE_SOURCE_DIR}/OPTYap/locks_sparc.h
${CMAKE_SOURCE_DIR}/packages/cplint
${CMAKE_SOURCE_DIR}/packages/CLPBN/examples
${CMAKE_SOURCE_DIR}/packages/CLPBN/horus
@ -70,9 +64,18 @@ ${CMAKE_SOURCE_DIR}/packages/python/swig
${CMAKE_SOURCE_DIR}/packages/yap-lbfgs/liblbfgs-1.10
${CMAKE_SOURCE_DIR}/packages/swi-minisat2
${CMAKE_SOURCE_DIR}/library/dialect/swi/os
)
set(DOCS_EXCLUDE_
${CMAKE_SOURCE_DIR}/C/traced_absmi_insts.h
${CMAKE_SOURCE_DIR}/H/globals.h
${CMAKE_SOURCE_DIR}/OPTYap/locks_alpha_funcs.h
${CMAKE_SOURCE_DIR}/OPTYap/locks_mips_funcs.h
${CMAKE_SOURCE_DIR}/OPTYap/locks_sparc.h
${CMAKE_SOURCE_DIR}/*/bprolog/*
${CMAKE_SOURCE_DIR}/*/prism/*
${CMAKE_SOURCE_DIR}/*/gecodde/[345]*
${CMAKE_SOURCE_DIR}/*/gecode/[345]*
${CMAKE_SOURCE_DIR}/packages/gecode/gecode3_yap.cc
${CMAKE_SOURCE_DIR}/packages/gecode/gecode4_yap.cc
${CMAKE_SOURCE_DIR}/packages/gecode/gecode5_yap.cc
@ -82,7 +85,7 @@ ${CMAKE_SOURCE_DIR}/*/bprolog/*
${CMAKE_SOURCE_DIR}/packages/gecode/gecode3_yap_hand_written.yap
${CMAKE_SOURCE_DIR}/packages/gecode/gecode4_yap_hand_written.yap
${CMAKE_SOURCE_DIR}/packages/gecode/gecode5_yap_hand_written.yap
*/CMakeFiles/* *~ */#*
*/CMakeFiles/*
)
@ -92,6 +95,11 @@ foreach(i ${DOCS_EXCLUDE_})
endforeach(i ${DOCS_EXCLUDE_})
foreach(i ${DOCS_DIR_EXCLUDE_})
string(APPEND DOCS_DIR_EXCLUDE ${i} " ")
endforeach(i ${DOCS_DIR_EXCLUDE_})
# add a target to generate API documentation with Doxygen
@ -102,6 +110,7 @@ endforeach(i ${DOCS_EXCLUDE_})
SET(DOC_INPUT_FILES_
${CMAKE_SOURCE_DIR}/docs/md
${CMAKE_SOURCE_DIR}/pl
${CMAKE_SOURCE_DIR}/packages/ProbLog
${CMAKE_SOURCE_DIR}/CXX
${CMAKE_SOURCE_DIR}/OPTYap
${CMAKE_SOURCE_DIR}/C
@ -110,7 +119,8 @@ endforeach(i ${DOCS_EXCLUDE_})
${CMAKE_SOURCE_DIR}/os
${CMAKE_SOURCE_DIR}/library
${CMAKE_SOURCE_DIR}/swi/library
${CMAKE_SOURCE_DIR}/packages
#${CMAKE_SOURCE_DIR}/packages
${CMAKE_SOURCE_DIR}/BEAM
)
foreach(i ${DOC_INPUT_FILES_})

9
docs/Doxyfile.in
View File

@ -296,10 +296,7 @@ OPTIMIZE_OUTPUT_FOR_PROLOG = YES
# Note that for custom extensions you also need to set FILE_PATTERNS otherwise
# the files are not read by doxygen.
EXTENSION_MAPPING = md \
pl=Prolog \
yap=Prolog \
ypp=Prolog
EXTENSION_MAPPING =
# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
# according to the Markdown format, which allows for more readable
@ -798,7 +795,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = @DOC_INPUT_FILES@
INPUT = @CMAKE_SOURCE_DIR@
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@ -884,7 +881,7 @@ RECURSIVE = YES
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE =
EXCLUDE = @DOCS_DIR_EXCLUDE@
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded

2
docs/md/packages.md
View File

@ -13,7 +13,7 @@ YAP packages {#packages}
+ @ref PFL
+ @ref ProbLogI
+ @subpage problog
+ @ref python

558
docs/md/problog.md
View File

@ -1,558 +0,0 @@
The Problog-I Language and Learning System {#ProbLogI}
============
[TOC]
This document is intended as a user guide for the users of ProbLog-I.
ProbLog is a probabilistic Prolog, a probabilistic logic programming
language, which is integrated in YAP-Prolog. Most of the work in ProbLog is now based on(Prolog-II), but we still maintain ProbLog-I in order to experiment with close integration of probabilistic nd logical systems.
@section InstallingProbLog Installing ProbLog
You will need the CUDD binary decision daagram generator. CUDD is available in Fedora Linux, MacPorts and other Linux distributions. If it is not available in your system, please fetch it from:
- [git@github.com:vscosta/cudd.git]
To compile CUDD you will need to run:
- `./configure --enable-dynamic=true`
- `make`
- `make -j install`
@section RunningProbLog Running ProbLog
To run ProbLog, go your ProbLog folder (eg. $\sim$/problog), and start
YAP (eg. $\sim$/yap/yap). This will start YAP with ProbLog
functionality.
To use ProbLog, the ProbLog module has to be loaded at the top of your
Prolog programs. This is done with the following statement:
> *:- use_module('../path/to/problog').*
where '../path/to/problog' represents the path to the problog.yap module
(ie. without the extension) from the current folder from where YAP was
started.
Similarly, to use the ProbLog learning module, use:
> *:- use_module('../path/to/problog_learning').*
@section EncodingProbs Encoding Probabilistic Facts
A probabilistic fact is encoded in ProbLog by preceding a predicate with
a probability value. For example:
> *0.5::heads(_).*
encodes the fact that there's 50% chance of getting heads when tossing
an unbiassed coin.
@subsection EncodingPars Encoding Parameter Learning Facts
Instead of probabilities every fact has a t( ) prefix. The t stands for
tunable and indicate that ProbLog should learn the probability. The
number between the parentheses indicates the ground truth probability.
It is ignored by the learning algorithm and if you do not know the
ground truth, you can write t(_). The ground truth is used after
learning to estimate the distance of the learned model parameters to the
ground truth model parameters. For example:
> t(0.5)::heads(1).
@section ProbPreds ProbLog Predicates
This chapter describes the predicates defined by ProbLog for evaluating
the probability of queries.
In the description of the arguments of functors the following notation
will be used:
- a preceding plus sign will denote an argument as an \"input
argument\" - it cannot be a free variable at the time of the call
- a preceding minus sign will denote an \"output argument\"
- an argument with no preceding symbol can be used in both ways
@pred problog_max(+G, -Prob, -FactsUsed)
This predicate returns the most likely explanation of proving the goal G
and the facts used in achieving this explanation.
@pred problog_exact(+G, -Prob, -Status)
This predicate returns the exact total probability of achieving the goal
G and the status of the query.
@pred problog_kbest(+G, +K, -Prob, -Status)
This predicate returns the sum of the probabilities of the best K proofs
of achieving the goal G and the status of the query.
@pred problog_montecarlo(+G, +Interval_width, -Prob)
This predicate approximates the probability of achieving the goal G by
using a Monte Carlo approach, with 95% confidence in the given interval
width.
@pred problog_delta(+G , +Interval_width, -Bound_low, -Bound_up, Status)
This predicate returns the lower and upper bound of the probability of
achieving the goal G by using an iterative deepening approach with the
given interval width.
@pred problog_threshold(+G , +Prob, -Bound_low, -Bound_up, -Status)
This predicate returns the lower and upper bound of the probability of
achieving the goal G obtained by cutting the sld tree at the given
probability for each branch.
@pred problog_low(+G, +Prob, -Bound_low, -Status)
This predicate returns the lower bound of the probability of achieving
the goal G obtained by cutting the sld tree at the given probability for
each branch.
@section ProbParLearnPreds ProbLog Parameter Learning Predicates
@pred example(+N, +Q, +Prob)
This predicate specifies an example. Every example has as input a unique
identifier (N), a query (Q) and a probability (Prob) associated with it.
Instead of queries, you can also give proofs as training example. They
are encoded as the conjunction of the probabilistic facts used in the
proof.
@pred test_example(+N, +Q, +Prob)
This predicate specifies a test example. Every test example has as input
a unique identifier (N), a query (Q) and a probability (Prob) associated
with it.
Test examples are ignored during learning but are used afterwards to
check the performance of the model. The ID namespace is shared between
the test examples and the training examples and you may only reuse an ID
if the queries are identical.
@pred do_learning(+N).
Starts the learning algorithm with N iterations.
@pred do_learning(+N, +Epsilon).
Starts the learning algorithm. The learning will stop after N iterations
or if the difference of the Mean Squared Error (MSE) between two
iterations gets smaller than Epsilon - depending on what happens first.
@paragraph Learning Output
---------------
The output is created in the output subfolder of the current folder
where YAP was started. There you will find the file log.dat which
contains MSE on training and test set for every iteration, the timings,
and some metrics on the gradient in CSV format. The files
factprobs_N.pl contain the fact probabilities after the Nth iteration
and the files predictions_N.pl contain the estimated probabilities for
each training and test example - per default these file are generated
every 5th iteration only.
@section ProbMisc Miscelaneous
Both the learning and the inference module have various parameters, or
flags, that can be adjusted by the user. The following predicates are
defined by ProbLog to access and set these flags.
@pred problog_flags
This predicate lists all the flags name, value, domain and description.
@pred problog_flag(+Name, -Value)
This predicate gives the value of the flag with the specified name. The
supported flags are:
- `use_db_trie`
Flag telling whether to use the builtin trie to trie transformation. The
possible values for this flag are true or false.
- `db_trie_opt_lvl`
Sets the optimization level for the trie to trie transformation The
possible values for this flag are any integer
- `compare_opt_lvl`
Flag telling whether to use comparison mode for the optimization level.
The possible values for this flag are true or false.
- `db_min_prefix`
Sets the minimum size of the prefix for dbtrie to optimize. The possible
values for this flag are any integer
- `use_naive_trie`
Flag telling whether to use the naive algorithm to generate bdd scripts.
The possible values for this flag are true or false.
- `use_old_trie`
Flag telling whether to use the old not nested trie to trie
transformation. The possible values for this flag are true or false.
- `use_dec_trie`
Flag telling whether to use the decomposition method. The possible
values for this flag are true or false.
- `subset_check`
Flag telling whether to perform subset check in nested tries. The
possible values for this flag are true or false.
- `deref_terms`
Flag telling whether to dereference BDD terms after their last use. The
possible values for this flag are true or false.
- `trie_preprocess`
Flag telling whether to perform a preprocess step to nested tries. The
possible values for this flag are true or false.
- `refine_anclst`
Flag telling whether to refine the ancestor list with their children.
The possible values for this flag are true or false.
- `anclst_represent`
Flag that sets the representation of the ancestor list. The possible
values for this flag are list or integer
- `max_depth`
Sets the maximum proof depth. The possible values for this flag are any
integer.
- `retain_tables`
Flag telling whether to retain tables after the query. The possible
values for this flag are true or false.
- `mc_batchsize`
Flag related to Monte Carlo Sampling that sets the number of samples
before update. The possible values for this flag are any integer greater
than zero.
- `min_mc_samples`
Flag related to Monte Carlo Sampling that sets the minimum number of
samples before convergence. The possible values for this flag are any
integer greater than or equal to zero.
- `max_mc_samples`
Flag related to Monte Carlo Sampling that sets the maximum number of
samples waiting to converge. The possible values for this flag are any
integer greater than or equal to zero.
- `randomizer`
Flag related to Monte Carlo Sampling telling whether the random numbers
are repeatable or not. The possible values for this flag are repeatable
or nonrepeatable.
- `search_method`
Flag related to DNF Monte Carlo Sampling that sets the search method for
picking the proof. The possible values for this flag are linear or
binary.
- `represent_world`
Flag related to Monte Carlo Sampling that sets the structure that
represents sampled world. The possible values for this flag are list,
record, array or hash_table
- `first_threshold`
Flag related to inference that sets the starting threshold of iterative
deepening. The possible values for this flag are a number in the
interval (0,1).
- `last_threshold`
Flag related to inference that sets the stopping threshold of iterative
deepening. The possible values for this flag are a number in the
interval (0,1).
- `id_stepsize`
Flag related to inference that sets the threshold shrinking factor of
iterative deepening. The possible values for this flag are a number in
the interval \[0,1\].
- `prunecheck`
Flag related to inference telling whether to stop derivations including
all facts of known proofs. The possible values for this flag are on or
off.
- `maxsteps`
Flag related to inference that sets the max. number of prob. steps per
derivation. The possible values for this flag are any integer greater
than zero.
- `mc_logfile`
Flag related to MCMC that sets the logfile for montecarlo. The possible
values for this flag are any valid filename.
- `bdd_time`
Flag related to BDD that sets the BDD computation timeout in seconds.
The possible values for this flag are any integer greater than zero.
- `bdd_par_file`
Flag related to BDD that sets the file for BDD variable parameters. The
possible values for this flag are any valid filename.
- `bdd_result`
Flag related to BDD that sets the file to store result calculated from
BDD. The possible values for this flag are any valid filename.
- `bdd_file`
Flag related to BDD that sets the file for the BDD script. The possible
values for this flag are any valid filename.
- `save_bdd`
Flag related to BDD telling whether to save BDD files for (last) lower
bound. The possible values for this flag are true or false.
- `dynamic_reorder`
Flag related to BDD telling whether to use dynamic re-ordering for BDD.
The possible values for this flag are true or false.
- `bdd_static_order`
Flag related to BDD telling whether to use static order. The possible
values for this flag are true or false.
- `static_order_file`
Flag related to BDD that sets the file for BDD static order. The
possible values for this flag are any valid filename.
- `verbose`
Flag telling whether to output intermediate information. The possible
values for this flag are true or false.
- `show_proofs`
Flag telling whether to output proofs. The possible values for this flag
are true or false.
- `triedump`
Flag telling whether to generate the file: trie_file containing the
trie structure. The possible values for this flag are true or false.
- `dir`
Flag telling the location of the output files directory. The possible
values for this flag are any valid directory name.
set_problog_flag
------------------
@pred set_problog_flag(+Name, +Value)
This predicate sets the value of the given flag. The supported flags are
the ones listed in above.
learning_flags
---------------
@pred learning_flags
This predicate lists all the learning flags name, value, domain and
description.
learning_flag
--------------
@pred learning_flag(+Name, -Value)
This predicate gives the value of the learning flag with the specified
name. The supported flags are:
- `output_directory`
Flag setting the directory where to store results. The possible values
for this flag are any valid path name.
- `query_directory`
Flag setting the directory where to store BDD files. The possible values
for this flag are any valid path name.
- `verbosity_level`
Flag telling how much output shall be given. The possible values for
this flag are an integer between 0 and 5 (0=nothing, 5=all).
- `reuse_initialized_bdds`
Flag telling whether to reuse BDDs from previous runs. The possible
values for this flag are true or false.
- `rebuild_bdds`
Flag telling whether to rebuild BDDs every nth iteration. The possible
values for this flag are any integer greater or equal to zero (0=never).
- `check_duplicate_bdds`
Flag telling whether to store intermediate results in hash table. The
possible values for this flag are true or false.
- `init_method`
Flag setting the ProbLog predicate to search proofs. The possible values
for this flag are of the form: (+Query,-P,+BDDFile,+ProbFile,+Call). For
example: A,B,C,D,problog_kbest_save(A,100,B,E,C,D)
- `probability_initializer`
Flag setting the ProbLog predicate to initialize probabilities. The
possible values for this flag are of the form: (+FactID,-P,+Call). For
example: A,B,random_probability(A,B)
- `log_frequency`
Flag telling whether to log results every nth iteration. The possible
values for this flag are any integer greater than zero.
- `alpha`
Flag setting the weight of negative examples. The possible values for
this flag are number or \"auto\" (auto=n_p/n_n).
- `slope`
Flag setting the slope of the sigmoid function. The possible values for
this flag are any real number greater than zero.
- `learning_rate`
Flag setting the default Learning rate (if line_search=false) The
possible values for this flag are any number greater than zero or
\"examples"
- `line_search`
Flag telling whether to use line search to estimate the learning rate.
The possible values for this flag are true or false.
- `line_search_tau`
Flag setting the Tau value for line search. The possible values for this
flag are a number in the interval (0,1).
- `line_search_tolerance`
Flag setting the tolerance value for line search. The possible values
for this flag are any number greater than zero.
- `line_search_interval`
Flag setting the interval for line search. The possible values for this
flag are of the form a,b where a and b are numbers and define an
interval with $0<=a<b$
- `line_search_never_stop`
Flag telling whether to make tiny step if line search returns 0. The
possible values for this flag are true or false.
set_learning_flag
-------------------
@pred set_learning_flag(+Name, +Value)
This predicate sets the value of the given learning flag. The supported
flags are the ones listed in above.
Further Help
============
To access the help information in ProbLog type:
@pred problog_help.

66
packages/ProbLog/problog.md Normal file
View File

@ -0,0 +1,66 @@
The Problog-I Language and Learning System {#problog}
=====================================
[TOC]
This document is intended as a user guide for the users of ProbLog-I.
ProbLog is a probabilistic Prolog, a probabilistic logic programming
language, which is integrated in YAP-Prolog. Most of the work in ProbLog is now based on(Prolog-II), but we still maintain ProbLog-I in order to experiment with close integration of probabilistic nd logical systems.
@section InstallingProbLog Installing ProbLog
You will need the CUDD binary decision daagram generator. CUDD is available in Fedora Linux, MacPorts and other Linux distributions. If it is not available in your system, please fetch it from:
- [git@github.com:vscosta/cudd.git]
To compile CUDD you will need to run:
- `./configure --enable-dynamic=true`
- `make`
- `make -j install`
@section RunningProbLog Running ProbLog
To run ProbLog, go your ProbLog folder (eg. $\sim$/problog), and start
YAP (eg. $\sim$/yap/yap). This will start YAP with ProbLog
functionality.
To use ProbLog, the ProbLog module has to be loaded at the top of your
Prolog programs. This is done with the following statement:
> *:- use_module('../path/to/problog').*
where '../path/to/problog' represents the path to the problog.yap module
(ie. without the extension) from the current folder from where YAP was
started.
Similarly, to use the ProbLog learning module, use:
> *:- use_module('../path/to/problog_learning').*
@section EncodingProbs Encoding Probabilistic Facts
A probabilistic fact is encoded in ProbLog by preceding a predicate with
a probability value. For example:
> *0.5::heads(_).*
encodes the fact that there's 50% chance of getting heads when tossing
an unbiassed coin.
@subsection EncodingPars Encoding Parameter Learning Facts
Instead of probabilities every fact has a t( ) prefix. The t stands for
tunable and indicate that ProbLog should learn the probability. The
number between the parentheses indicates the ground truth probability.
It is ignored by the learning algorithm and if you do not know the
ground truth, you can write t(_). The ground truth is used after
learning to estimate the distance of the learned model parameters to the
ground truth model parameters. For example:
> t(0.5)::heads(1).

519
packages/ProbLog/problog.yap
View File

@ -206,124 +206,30 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% ProbLog inference
%
% assumes probabilistic facts as Prob::Fact and clauses in normal Prolog format
%
% provides following inference modes (16/12/2008):
% - approximation with interval width Delta (IJCAI07): problog_delta(+Query,+Delta,-Low,-High,-Status)
% - bounds based on single probability threshold: problog_threshold(+Query,+Threshold,-Low,-High,-Status)
% - as above, but lower bound only: problog_low(+Query,+Threshold,-Low,-Status)
% - lower bound based on K most likely proofs: problog_kbest(+Query,+K,-Low,-Status)
% - explanation probability (ECML07): problog_max(+Query,-Prob,-FactsUsed)
% - exact probability: problog_exact(+Query,-Prob,-Status)
% - sampling: problog_montecarlo(+Query,+Delta,-Prob)
%
%
% angelika.kimmig@cs.kuleuven.be
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
/**
@defgroup ProbLog1 The Leuven ProbLog1 System
@ingroup packages
@brief This document is intended as a user guide for the users of ProbLog. ProbLog is a probabilistic Prolog, a probabilistic logic programming language, which is integrated in YAP-Prolog.
## Installing ProbLog
### Requirements
For installing and running ProbLog, the following are required:
+ a reasonable up-to-date computer, running Linux or Mac OS
+ YAP Prolog 5.1.3 (for Mac OS the more recent version 5.1.4 is needed) or YAP-6
### Download
To install ProbLog1, it is first necessary to download SimpleCUDD or CUDD. YAP Prolog also needs to be downloaded if it is not already installed on the machine
For downloading SimpleCUDD, go to:
+ http://www.cs.kuleuven.be/$sim$theo/tools/SimpleCUDD.tar.gz
You can also use the CUDD interface package in YAP. You will need to
1. If a Fedora user, CUDD is just available.
2. If a Mac user, there is a ports package.
3. Otherwise, you can obtain the version at . This version compiles under WIN32.
Last, when you configure YAP you need to add the options --with-cidd --enable-bddlib. Binary distributed versions already have the interface.
## Running ProbLog
To use ProbLog, the ProbLog module has to be loaded at the top of your Prolog programs. This is done with the following statement:
~~~~
:- use_module(library(problog)).
~~~~
Similarly, to compile the ProbLog learning module, use:
~~~~
:- use_module(library(problog_learning)).
~~~~
or
~~~~
:- use_module(library(problog_learning_lbdd)).
~~~~
## Encoding Probabilistic Facts
A probabilistic fact is encoded in ProbLog by preceding a predicate with a probability value. For example:
~~~~
0.5::heads(_).
~~~~
encodes the fact that there's 50% chance of getting heads when tossing an unbiassed coin.
### Encoding Parameter Learning Facts
Instead of probabilities every fact has a t( ) prefix. The t stands for tunable and indicate that ProbLog should learn the probability. The number between the parentheses indicates the ground truth probability. It is ignored by the learning algorithm and if you do not know the ground truth, you can write t(_). The ground truth is used after learning to estimate the distance of the learned model parameters to the ground truth model parameters. For example:
~~~~
t(0.5)::heads(_).
~~~~
*/
/** @defgroup ProbLogPredicates ProbLog Predicates
@ingroup ProbLog1
This chapter describes the predicates defined by ProbLog for evaluating the probability of queries.
In the description of the arguments of functors the following notation will be used:
+ a preceding plus sign will denote an argument as an "input argument" - it cannot be a free variable at the time of the call
+ a preceding minus sign will denote an "output argument"
+ an argument with no preceding symbol can be used in both ways
/**
* @pred problog_max(+G, -Prob, -FactsUsed)
/** @defgroup ProbLogPredicates Computing Probabilities of Events
* @ingroup problog
*
This predicate returns the most likely explanation of proving the goal G and the facts used in achieving this explanation.
*/
/**
* @pred problog_exact(+G, -Prob, -Status)
* This chapter describes the predicates defined by ProbLog for evaluating the probability of queries.
*
This predicate returns the exact total probability of achieving the goal G and the status of the query.
*/
/**
* @pred problog_kbest(+G, +K, -Prob, -Status)
*@{
*
This predicate returns the sum of the probabilities of the best K proofs of achieving the goal G and the status of the query.
*/
/**
* @pred problog_montecarlo(+G, +Interval_width, -Prob)
* ProbLog inference
*
This predicate approximates the probability of achieving the goal G by using a Monte Carlo approach, with 95% confidence in the given interval width.
* assumes probabilistic facts as Prob::Fact and clauses in normal Prolog format
*
* provides following inference modes (16/12/2008):
* - approximation with interval width Delta (IJCAI07): problog_delta(+Query,+Delta,-Low,-High,-Status)
* - bounds based on single probability threshold: problog_threshold(+Query,+Threshold,-Low,-High,-Status)
* - as above, but lower bound only: problog_low(+Query,+Threshold,-Low,-Status)
* - lower bound based on K most likely proofs: problog_kbest(+Query,+K,-Low,-Status)
* - explanation probability (ECML07): problog_max(+Query,-Prob,-FactsUsed)
* - exact probability: problog_exact(+Query,-Prob,-Status)
* - sampling: problog_montecarlo(+Query,+Delta,-Prob)
*
*
* angelika.kimmig@cs.kuleuven.be
*/
/**
@ -344,10 +250,19 @@ This predicate returns the lower and upper bound of the probability of achieving
This predicate returns the lower bound of the probability of achieving the goal G obtained by cutting the sld tree at the given probability for each branch.
*/
/**
@pred problog_help.
To access the help information in ProbLog type:
*/
%%@}
%%@{
/**
@defgroup ProbLogParameterLearning ProbLog Parameter Learning Predicates
@ingroup ProbLog1
@ingroup ProbLogI
@{
*/
@ -381,319 +296,20 @@ The output is created in the output subfolder of the current folder where YAP wa
1
Starts the learning algorithm. The learning will stop after N iterations or if the difference of the Mean Squared Error (MSE) between two iterations gets smaller than Epsilon - depending on what happens first.
*/
@paragraph Learning Output
---------------
%% @}
/** @defgroup ProbLogMiscellaneous ProbLog Miscellaneous Predicates
@ingroup ProbLog1
@{
Both the learning and the inference module have various parameters, or flags, that can be adjusted by the user.
The following predicates are defined by ProbLog to access and set these flags.
The output is created in the output subfolder of the current folder
where YAP was started. There you will find the file log.dat which
contains MSE on training and test set for every iteration, the timings,
and some metrics on the gradient in CSV format. The files
factprobs_N.pl contain the fact probabilities after the Nth iteration
and the files predictions_N.pl contain the estimated probabilities for
each training and test example - per default these file are generated
every 5th iteration only.
*/
/**
* @pred problog_flags
*
This predicate lists all the flags name, value, domain and description.
*/
/** @pred problog_flag(+Name, -Value)
This predicate gives the value of the flag with the specified name. The supported flags are:
+ use_db_trie
Flag telling whether to use the builtin trie to trie transformation.
The possible values for this flag are true or false.
+ db_trie_opt_lvl
Sets the optimization level for the trie to trie transformation
The possible values for this flag are any integer
+ compare_opt_lvl
Flag telling whether to use comparison mode for the optimization level.
The possible values for this flag are true or false.
+ db_min_prefix
Sets the minimum size of the prefix for dbtrie to optimize.
The possible values for this flag are any integer
+ use_naive_trie
Flag telling whether to use the naive algorithm to generate bdd scripts.
The possible values for this flag are true or false.
+ use_old_trie
Flag telling whether to use the old not nested trie to trie transformation.
The possible values for this flag are true or false.
+ use_dec_trie
Flag telling whether to use the decomposition method.
The possible values for this flag are true or false.
+ subset_check
Flag telling whether to perform subset check in nested tries.
The possible values for this flag are true or false.
+ deref_terms
Flag telling whether to dereference BDD terms after their last use.
The possible values for this flag are true or false.
+ trie_preprocess
Flag telling whether to perform a preprocess step to nested tries.
The possible values for this flag are true or false.
+ refine_anclst
Flag telling whether to refine the ancestor list with their children.
The possible values for this flag are true or false.
+ anclst_represent
Flag that sets the representation of the ancestor list.
The possible values for this flag are list or integer
+ max_depth
Sets the maximum proof depth.
The possible values for this flag are any integer.
+ retain_tables
Flag telling whether to retain tables after the query.
The possible values for this flag are true or false.
+ mc_batchsize
Flag related to Monte Carlo Sampling that sets the number of samples before update.
The possible values for this flag are any integer greater than zero.
+ min_mc_samples
Flag related to Monte Carlo Sampling that sets the minimum number of samples before convergence. The possible values for this flag are any integer greater than or equal to zero.
+ max_mc_samples
Flag related to Monte Carlo Sampling that sets the maximum number of samples waiting to converge.
The possible values for this flag are any integer greater than or equal to zero.
+ randomizer
Flag related to Monte Carlo Sampling telling whether the random numbers are repeatable or not.
The possible values for this flag are repeatable or nonrepeatable.
+ search_method
Flag related to DNF Monte Carlo Sampling that sets the search method for picking the proof.
The possible values for this flag are linear or binary.
+ represent_world
Flag related to Monte Carlo Sampling that sets the structure that represents sampled world.
The possible values for this flag are list, record, array or hash_table
+ first_threshold
Flag related to inference that sets the starting threshold of iterative deepening.
The possible values for this flag are a number in the interval (0,1).
+ last_threshold
Flag related to inference that sets the stopping threshold of iterative deepening.
The possible values for this flag are a number in the interval (0,1).
+ id_stepsize
Flag related to inference that sets the threshold shrinking factor of iterative deepening.
The possible values for this flag are a number in the interval [0,1].
+ prunecheck
Flag related to inference telling whether to stop derivations including all facts of known proofs.
The possible values for this flag are on or off.
+ maxsteps
Flag related to inference that sets the max. number of prob. steps per derivation.
The possible values for this flag are any integer greater than zero.
+ mc_logfile
Flag related to MCMC that sets the logfile for montecarlo.
The possible values for this flag are any valid filename.
+ bdd_time
Flag related to BDD that sets the BDD computation timeout in seconds.
The possible values for this flag are any integer greater than zero.
+ bdd_par_file
Flag related to BDD that sets the file for BDD variable parameters.
The possible values for this flag are any valid filename.
+ bdd_result
Flag related to BDD that sets the file to store result calculated from BDD.
The possible values for this flag are any valid filename.
+ bdd_file
Flag related to BDD that sets the file for the BDD script.
The possible values for this flag are any valid filename.
+ save_bdd
Flag related to BDD telling whether to save BDD files for (last) lower bound.
The possible values for this flag are true or false.
+ dynamic_reorder
Flag related to BDD telling whether to use dynamic re-ordering for BDD.
The possible values for this flag are true or false.
+ bdd_static_order
Flag related to BDD telling whether to use static order.
The possible values for this flag are true or false.
+ static_order_file
Flag related to BDD that sets the file for BDD static order.
The possible values for this flag are any valid filename.
+ verbose
Flag telling whether to output intermediate information.
The possible values for this flag are true or false.
+ show_proofs
Flag telling whether to output proofs.
The possible values for this flag are true or false.
+ triedump
Flag telling whether to generate the file: trie_file containing the trie structure.
The possible values for this flag are true or false.
+ dir
Flag telling the location of the output files directory.
The possible values for this flag are any valid directory name.
*/
/** @pred set_problog_flag(+Name, +Value)
the predicate sets the value of the given flag. The supported flags are the ones listed in above
*/
/** @pred learning_flags
the predicate sets the value of the given flag. The supported flags are the ones listed in above
*/
/** @pred learning_flag(+Name, -Value)
This predicate gives the value of the learning flag with the specified name. The supported flags are:
+ output_directory
Flag setting the directory where to store results.
The possible values for this flag are any valid path name.
+ query_directory
Flag setting the directory where to store BDD files.
The possible values for this flag are any valid path name.
+ verbosity_level
Flag telling how much output shall be given.
The possible values for this flag are an integer between 0 and 5 (0=nothing, 5=all).
+ reuse_initialized_bdds
Flag telling whether to reuse BDDs from previous runs.
The possible values for this flag are true or false.
+ rebuild_bdds
Flag telling whether to rebuild BDDs every nth iteration.
The possible values for this flag are any integer greater or equal to zero (0=never).
+ check_duplicate_bdds
Flag telling whether to store intermediate results in hash table.
The possible values for this flag are true or false.
+ init_method
Flag setting the ProbLog predicate to search proofs.
The possible values for this flag are of the form: (+Query,-P,+BDDFile,+ProbFile,+Call). For example: A,B,C,D,problog_kbest_save(A,100,B,E,C,D)
+ probability_initializer
Flag setting the ProbLog predicate to initialize probabilities.
The possible values for this flag are of the form: (+FactID,-P,+Call). For example: A,B,random_probability(A,B)
+ log_frequency
Flag telling whether to log results every nth iteration.
The possible values for this flag are any integer greater than zero.
+ alpha
Flag setting the weight of negative examples.
The possible values for this flag are number or "auto" (auto=n_p/n_n).
+ slope
Flag setting the slope of the sigmoid function.
The possible values for this flag are any real number greater than zero.
+ learning_rate
Flag setting the default Learning rate (if line_search=false)
The possible values for this flag are any number greater than zero or "examples``
+ line_search
Flag telling whether to use line search to estimate the learning rate.
The possible values for this flag are true or false.
+ line_search_tau
Flag setting the Tau value for line search.
The possible values for this flag are a number in the interval (0,1).
+ line_search_tolerance
Flag setting the tolerance value for line search.
The possible values for this flag are any number greater than zero.
+ line_search_interval
Flag setting the interval for line search.
*/
%% @}
:- module(problog, [problog_koptimal/3,
problog_koptimal/4,
@ -2820,21 +2436,25 @@ eval_upper(N,UpP,ok) :-
up(_,UpP)
).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% explanation probability - returns list of facts used or constant 'unprovable' as third argument
% problog_max(+Goal,-Prob,-Facts)
%
% uses iterative deepening with samw parameters as bounding algorithm
% threshold gets adapted whenever better proof is found
%
% uses local dynamic predicates max_probability/1 and max_proof/1
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
/**
@pred problog_max(+G, -Prob, -FactsUsed)
This predicate returns the most likely explanation of proving the goal G
and the facts used in achieving this explanation.
explanation probability - returns list of facts used or constant 'unprovable' as third argument
problog_max(+Goal,-Prob,-Facts)
uses iterative deepening with samw parameters as bounding algorithm
threshold gets adapted whenever better proof is found
uses local dynamic predicates max_probability/1 and max_proof/1
*/
problog_max(Goal, Prob, Facts) :-
problog_flag(first_threshold,InitT),
init_problog_max(InitT),
problog_control(off,up),
problog_max_id(Goal, Prob, FactIDs),% theo todo
problog_max_id(Goal, Prob, FactIDs),theo todo
( FactIDs = [_|_] -> get_fact_list(FactIDs, Facts);
Facts = FactIDs).
@ -2919,6 +2539,12 @@ problog_kbest_save(Goal, K, Prob, Status, BDDFile, ParamFile) :-
% ;
% true).
/**
* @pred problog_kbest(+G, +K, -Prob, -Status)
*
* This predicate returns the sum of the probabilities of the best K proofs of achieving the goal G and the status of the query.
*/
problog_kbest(Goal, K, Prob, Status) :-
problog_flag(first_threshold,InitT),
init_problog_kbest(InitT),
@ -3060,13 +2686,14 @@ to_external_format_with_reverse([LogP-FactIDs|Intern],Acc,Extern) :-
Facts = FactIDs),
to_external_format_with_reverse(Intern,[Prob-Facts|Acc],Extern).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% exact probability
% problog_exact(+Goal,-Prob,-Status)
%
% using all proofs = using all proofs with probability > 0
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
/**
* @pred problog_exact(+G, -Prob, -Status)
*
This predicate returns the exact total probability of achieving the goal G and the status of the query.
using all proofs = using all proofs with probability > 0
*/
problog_exact(Goal,Prob,Status) :-
problog_control(on, exact),
problog_low(Goal,0,Prob,Status),
@ -3132,13 +2759,17 @@ problog_exact_nested(Goal, Prob, Status):-
delete_ptree(Trie_Completed_Proofs),
problog_restore_state(State).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% probability by sampling:
% running another N samples until 95percentCI-width<Delta
% lazy sampling using three-valued array indexed by internal fact IDs for ground facts,
% internal database keys mc_true and mc_false for groundings of non-ground facts (including dynamic probabilities)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
/**
* @pred problog_montecarlo(+G, +Interval_width, -Prob)
*
* This predicate approximates the probability of achieving the goal G by using a Monte Carlo approach, with 95% confidence in the given interval width.
*
* probability by sampling:
* running another N samples until 95percentCI-width<Delta
* lazy sampling using three-valued array indexed by internal fact IDs for ground facts,
* internal database keys mc_true and mc_false for groundings of non-ground facts (including dynamic probabilities)
*/
problog_montecarlo(Goal,Delta,Prob) :-
retractall(mc_prob(_)),
nb_getval(probclause_counter,ID), !,

312
packages/ProbLog/problog/flags.yap
View File

@ -204,6 +204,8 @@
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% @file problog/flags
:-module(flags, [problog_define_flag/4,
problog_define_flag/5,
problog_define_flag/6,
@ -218,6 +220,314 @@
:- use_module(logger).
:- use_module(library(system), [file_exists/1, delete_file/1]).
/** @defgroup ProbLogMiscellaneous ProbLog Miscellaneous Predicates
@ingroup problog
@{
Both the learning and the inference module have various parameters, or flags, that can be adjusted by the user.
The following predicates are defined by ProbLog to access and set these flags.
*/
/**
* @pred problog_flags
*
This predicate lists all the flags name, value, domain and description.
*/
/** @pred problog_flag(+Name, -Value)
This predicate gives the value of the flag with the specified name. The supported flags are:
+ use_db_trie
Flag telling whether to use the builtin trie to trie transformation.
The possible values for this flag are true or false.
+ db_trie_opt_lvl
Sets the optimization level for the trie to trie transformation
The possible values for this flag are any integer
+ compare_opt_lvl
Flag telling whether to use comparison mode for the optimization level.
The possible values for this flag are true or false.
+ db_min_prefix
Sets the minimum size of the prefix for dbtrie to optimize.
The possible values for this flag are any integer
+ use_naive_trie
Flag telling whether to use the naive algorithm to generate bdd scripts.
The possible values for this flag are true or false.
+ use_old_trie
Flag telling whether to use the old not nested trie to trie transformation.
The possible values for this flag are true or false.
+ use_dec_trie
Flag telling whether to use the decomposition method.
The possible values for this flag are true or false.
+ subset_check
Flag telling whether to perform subset check in nested tries.
The possible values for this flag are true or false.
+ deref_terms
Flag telling whether to dereference BDD terms after their last use.
The possible values for this flag are true or false.
+ trie_preprocess
Flag telling whether to perform a preprocess step to nested tries.
The possible values for this flag are true or false.
+ refine_anclst
Flag telling whether to refine the ancestor list with their children.
The possible values for this flag are true or false.
+ anclst_represent
Flag that sets the representation of the ancestor list.
The possible values for this flag are list or integer
+ max_depth
Sets the maximum proof depth.
The possible values for this flag are any integer.
+ retain_tables
Flag telling whether to retain tables after the query.
The possible values for this flag are true or false.
+ mc_batchsize
Flag related to Monte Carlo Sampling that sets the number of samples before update.
The possible values for this flag are any integer greater than zero.
+ min_mc_samples
Flag related to Monte Carlo Sampling that sets the minimum number of samples before convergence. The possible values for this flag are any integer greater than or equal to zero.
+ max_mc_samples
Flag related to Monte Carlo Sampling that sets the maximum number of samples waiting to converge.
The possible values for this flag are any integer greater than or equal to zero.
+ randomizer
Flag related to Monte Carlo Sampling telling whether the random numbers are repeatable or not.
The possible values for this flag are repeatable or nonrepeatable.
+ search_method
Flag related to DNF Monte Carlo Sampling that sets the search method for picking the proof.
The possible values for this flag are linear or binary.
+ represent_world
Flag related to Monte Carlo Sampling that sets the structure that represents sampled world.
The possible values for this flag are list, record, array or hash_table
+ first_threshold
Flag related to inference that sets the starting threshold of iterative deepening.
The possible values for this flag are a number in the interval (0,1).
+ last_threshold
Flag related to inference that sets the stopping threshold of iterative deepening.
The possible values for this flag are a number in the interval (0,1).
+ id_stepsize
Flag related to inference that sets the threshold shrinking factor of iterative deepening.
The possible values for this flag are a number in the interval [0,1].
+ prunecheck
Flag related to inference telling whether to stop derivations including all facts of known proofs.
The possible values for this flag are on or off.
+ maxsteps
Flag related to inference that sets the max. number of prob. steps per derivation.
The possible values for this flag are any integer greater than zero.
+ mc_logfile
Flag related to MCMC that sets the logfile for montecarlo.
The possible values for this flag are any valid filename.
+ bdd_time
Flag related to BDD that sets the BDD computation timeout in seconds.
The possible values for this flag are any integer greater than zero.
+ bdd_par_file
Flag related to BDD that sets the file for BDD variable parameters.
The possible values for this flag are any valid filename.
+ bdd_result
Flag related to BDD that sets the file to store result calculated from BDD.
The possible values for this flag are any valid filename.
+ bdd_file
Flag related to BDD that sets the file for the BDD script.
The possible values for this flag are any valid filename.
+ save_bdd
Flag related to BDD telling whether to save BDD files for (last) lower bound.
The possible values for this flag are true or false.
+ dynamic_reorder
Flag related to BDD telling whether to use dynamic re-ordering for BDD.
The possible values for this flag are true or false.
+ bdd_static_order
Flag related to BDD telling whether to use static order.
The possible values for this flag are true or false.
+ static_order_file
Flag related to BDD that sets the file for BDD static order.
The possible values for this flag are any valid filename.
+ verbose
Flag telling whether to output intermediate information.
The possible values for this flag are true or false.
+ show_proofs
Flag telling whether to output proofs.
The possible values for this flag are true or false.
+ triedump
Flag telling whether to generate the file: trie_file containing the trie structure.
The possible values for this flag are true or false.
+ dir
Flag telling the location of the output files directory.
The possible values for this flag are any valid directory name.
*/
/** @pred set_problog_flag(+Name, +Value)
the predicate sets the value of the given flag. The supported flags are the ones listed in above
*/
/** @pred learning_flags
the predicate sets the value of the given flag. The supported flags are the ones listed in above
*/
/** @pred learning_flag(+Name, -Value)
This predicate gives the value of the learning flag with the specified name. The supported flags are:
+ output_directory
Flag setting the directory where to store results.
The possible values for this flag are any valid path name.
+ query_directory
Flag setting the directory where to store BDD files.
The possible values for this flag are any valid path name.
+ verbosity_level
Flag telling how much output shall be given.
The possible values for this flag are an integer between 0 and 5 (0=nothing, 5=all).
+ reuse_initialized_bdds
Flag telling whether to reuse BDDs from previous runs.
The possible values for this flag are true or false.
+ rebuild_bdds
Flag telling whether to rebuild BDDs every nth iteration.
The possible values for this flag are any integer greater or equal to zero (0=never).
+ check_duplicate_bdds
Flag telling whether to store intermediate results in hash table.
The possible values for this flag are true or false.
+ init_method
Flag setting the ProbLog predicate to search proofs.
The possible values for this flag are of the form: (+Query,-P,+BDDFile,+ProbFile,+Call). For example: A,B,C,D,problog_kbest_save(A,100,B,E,C,D)
+ probability_initializer
Flag setting the ProbLog predicate to initialize probabilities.
The possible values for this flag are of the form: (+FactID,-P,+Call). For example: A,B,random_probability(A,B)
+ log_frequency
Flag telling whether to log results every nth iteration.
The possible values for this flag are any integer greater than zero.
+ alpha
Flag setting the weight of negative examples.
The possible values for this flag are number or "auto" (auto=n_p/n_n).
+ slope
Flag setting the slope of the sigmoid function.
The possible values for this flag are any real number greater than zero.
+ learning_rate
Flag setting the default Learning rate (if line_search=false)
The possible values for this flag are any number greater than zero or "examples``
+ line_search
Flag telling whether to use line search to estimate the learning rate.
The possible values for this flag are true or false.
+ line_search_tau
Flag setting the Tau value for line search.
The possible values for this flag are a number in the interval (0,1).
+ line_search_tolerance
Flag setting the tolerance value for line search.
The possible values for this flag are any number greater than zero.
+ line_search_interval
Flag setting the interval for line search.
*/
problog_define_flag(Flag, Type, Description, DefaultValue):-
flag_define(Flag, Type, DefaultValue, Description).
@ -405,3 +715,5 @@ problog_flag_validate_interval( (V1,V2) ) :-
V1<V2.
*/
%% @}