.. HUGIN Python API documentation master file, created by
   sphinx-quickstart on Fri Jan 20 11:02:50 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

HUGIN Python API
================

These pages are meant as a help for developers programming against the
HUGIN Python API.  Brief descriptions are included for all classes and
their members.  For more detailed descriptions, please consult the
full documentation provided in the HUGIN API Reference Manual (the
api-manual.pdf file).


This documentation contains
---------------------------

* :ref:`genindex` of HUGIN Python Classes and functions

.. toctree::
   :maxdepth: 2

   apidoc
   examples




General Information
-------------------

The HUGIN Python API contains a high performance inference engine that
can be used as the core of knowledge based systems built using
Bayesian networks or LIMIDs (*Limited Memory Influence Diagrams*, a
generalization of ordinary influence diagrams).  Using probabilistic
descriptions of causal relationships in an application domain, a
knowledge engineer can build knowledge bases that model the domain.
Given this description, the HUGIN Decision Engine can perform fast and
accurate reasoning.

The HUGIN Python API is organized as an ordinary Python module.
Classes and member functions are provided for tasks such as
construction of networks, performing inference, etc.  The HUGIN Python
API also provides an exception based mechanism for handling errors.


Files
-----
The HUGIN Python API is provided as two files, a regular Python module
(.py-file) and a native library file (.dll/.so/.dylib depending on the
native platform).

*Python module*

- pyhugin98.py contains the HUGIN Python module for any platform.

*Native library file, depending on platform*

- pyhugin98.dll contains the native version of the HUGIN API for 32-bit Python on Windows
- pyhugin98-64.dll contains the native version of the HUGIN API for 64-bit Python on Windows
- libpyhugin98.so contains the native version of the HUGIN API for 32-bit Python on Linux
- libpyhugin98-64.so contains the native version of the HUGIN API for 64-bit Python on Linux
- libpyhugin98-64.dylib contains the native version of the HUGIN API for 64-bit Python on macOS

The native library files on Windows have a dependency on the Microsoft
Visual C++ 2015 Runtime.  If it is not already installed, it can be
downloaded here:

- Microsoft Visual C++ 2015 Redistributable Package
  <https://www.microsoft.com/en-us/download/details.aspx?id=48145>.

The Python interpreter must be able to load the relevant files, either
place the files in the same directory as your application Python
module or place them in your Python module directory, the path of
which must be exported as an environment variable PYTHONPATH.

The HUGIN Python API is a double-precision library.  Python version
2.7 and 3 or newer is supported.

Please refer to the HUGIN API Reference Manual (the api-manual.pdf
file) for detailed description of the HUGIN API functions.


Memory Management
-----------------

The HUGIN Python API is comprised of two parts: a Python part and a
native part written in C.  Contrary to objects within the Python
interpreter, native data objects are not automatically reclaimed (or
"garbage collected") when a program stops referring to them.
Therefore, some explicit memory management is needed in order to avoid
memory leaks.

For example, when a Python Domain object is no longer needed, it
should be deleted.  Deleting a Domain object will cause all the native
objects associated with the Domain object to be implicitly deleted:
the native Domain object, the native Node objects, etc.  At the same
time all Python objects corresponding to those native objects are
marked "dead" (that is, invoking methods on such objects will cause
'not alive' HuginExceptions).  When the Python program stops referring
to dead objects, the garbage collector can reclaim them.

Only objects that are not "owned by" other objects require explicit
deletion.  (For example, nodes are owned by a Domain or a Class
object; a Class object is owned by a ClassCollection object; etc.)  An
object owned by another object is automatically deleted when its owner
is deleted.

The following objects are not owned by other objects and must
therefore be explicitly deleted in the Python code:

* Domain objects
* ClassCollection objects
* DataSet objects
* Table objects created by the Domain.get_marginal() function
* Table objects created by the Node.get_distribution() function of continuous chance nodes


Acknowledgements
----------------

Hugin Expert A/S has participated in a number of projects funded by
the European Union.  Some projects have also received funding from
Innovation Fund Denmark.  See
<https://www.hugin.com/index.php/acknowledgments/> for the complete
list of projects.

The development of the functionality concerning the real-valued
FunctionNode type (introduced in Hugin 7.3) has been sponsored by
Danish mortgage credit institution Nykredit Realkredit
(<https://www.nykredit.dk/>).

The development of the functionality concerning the
DiscreteFunctionNode type as well as the AggregateExpression and
ProbabilityExpression operators (introduced in Hugin 7.7) has been
sponsored by the research project "Operational risk in banking and
finance."  The project is dedicated to strengthening management of
operational risk in the banking and finance sector, including
developing Basel II compliant operational risk measurement and
management tools in accordance with the Advanced Measurement Approach
(AMA).  The project is financed by the University of Stavanger and a
consortium of Norwegian banks consisting of Sparebank 1 SR-Bank,
Sparebank 1 SNN, Sparebank 1 SMN, Sparebanken Hedmark, and Sparebank 1
Oslo and Akershus.
