The Pyidp3 API reference

This page contains the API reference for Pyidp3. This is an entirely autogenerated page, based on the docstring that are inside the code. Some things might be wrong, or might be outdated. If you find any of such things, let me know and I’ll fix them (or make a pullrequest).

As the entire layout can be a bit awkward, I also autogenerated UML diagrams. This is the package structure:

And this is the entire class structure, with only the classnames:

For an overview of the entire class structure with methods and attributes, check the bottom of this page.

The typedIDP submodule:

This is the main, toplevel submodule and contains everything a normal user would need.

class pyidp3.typedIDP.Block(name)

An abstract superclass for the editable blocks. Should never be explicitly instantiated, but there’s no elegant way to enforce abstraction in python3. These editable blocks consist of: * Theory; * Structure; * Vocabulary; * Term.

There is no Main block, see further.

Raises:NotImplementedError – some of the methods need to be implemented by the subclass.

begin()

Generates the beginning of a Blockstring. This is just an opening bracket and enter for all blocktypes.

Returns:the begin of a block in IDP-form. Return type:str

content(objects)

Creates the actual content of the block, based on what it contains.

Parameters:objects (TODO) – TODO Returns:the content of the objects in IDP-form. Return type:str

end()

The ending of a Blockstring. This is the same for all the blocktypes. Consists of a closing bracket and a couple of enters.

Returns:the ending of a block in IDP-form. Return type:str

header()

The default header raises an error if it isn’t overwritten.

Raises:NotImplementedError – if it’s not overwritten.

method()

Returns:todo Return type:str

show(objects=None)

Function to fully generate a Block in IDP-interpretable string. Every block consists of a header, a begin section, a section containing objects, and an end.

The only Block without an ‘objects’ variable is the Term block.

Parameters:objects (TODO) – TODO Returns:the block in IDP-form. Return type:str

class pyidp3.typedIDP.IDP(executable='~/idp/usr/local/bin/idp')

A class containing everything needed to ‘use’ the IDP system. It allows adding and removing new constraints, functions, relations, … which it can then convert into a usable IDP script. This script can be piped into the idp executable, whose path is supplied in the init. The output can then be decoded and turned back into Pythonic data structures. This allows for a full interface in Python, and theoretically no much knowledge of IDP is needed. Although, it is possible (and in my opinion preferred) to supply most of the idpobjects already in IDP format, which requires IDP knowledges but removes the danger of converting Python to IDP.

Constant(typed_name, enumeration=None)

Adds a constant.

Parameters:

• typed_name (str) – the name of the constant, in IDP format.
• enumeration – this is currently not used. TODO: FIX!
• enumeration – list of values

Returns:

the constant itself

Return type:

Function

Constraint(formula, already_IDP=False)

Adds a constraint. There are two types of constraint:

1. Constraints with formula in the Python form;
2. Constraints with formula in the IDP form.

In the second case, the formula doesn’t need to be parsed into the IDP form. This is a ‘safer’ way of programming, but it requires more knowledge of the IDP system. In the first case, the Python form needs to be parsed into the IDP form. This is done by passing it on to the parse_formula function.

Parameters:

• formula (str) – the formula in either Python or IDP form
• already_IDP (bool) – a bool to flag what form the formula is in

Returns:

an IDP object

Return type:

IDPConstraint

Define(*args)

Method to make a definition. It can be called as “Define(Head,Body)” for a definition with only one rule, or it could be called as “Define([(H1,B1), (H2,B2), …])” for definitions with multiple rules. As last argument, a “already_idp” flag could be passed. This function is a bit experimental, best to format it as IDP and use the ‘already_idp’ flag.

Parameters:

• head (str) – the head of the rule
• body (str) – the body of the rule
• already_idp – flag of whether it’s in the correct form or not

type already_idp: bool

OR

Parameters:list (list of tuples) – tuples of heads and bodies Returns:the definition in IDP form Return type:IDPDefinition

Function(typed_name, enumeration=None, partial=False)

Adds a function. This function is either:

• Empty;
• Completely filled;
• Partial (not advised).

Parameters:

• typed_name (str) – the name of the function, in IDP format
• enumeration (dictionary) – dictionary containing the values of the function
• partial – flag to make partial function (not advised)

Partial:

bool

Returns:

an IDPEnumeratedFunction or IDPUnkownFunction object

Example:

Function(“Weight(Penalty): Number”, [penalty1:5, penalty2:15, penalty3:30])

would be formatted to:

Weight(Penalty) = {penalty1->5, penalty2->15, penalty3->30}

GeneratedFunction(typed_name, impl)

TODO: Document this! >:(

GeneratedPartialFunction(typed_name, impl)

TODO: Document this! >:(

Predicate(typed_name, enumeration=None, ct=False)

Adds a predicate. It can either be empty, or already (partially) filled.

Parameters:

• typed_name (str) – name of the predicate in IDP format
• enumeration – an x-dimensional array containing the data.

x needs to equal to the amount of variables there are in the IDP formatted predicate :type enumeration: list of str, int, float, … :returns: the Predicate in a datastructure :rtype: IDPEnumeratedPredicate or IDPUnknownPredicate

Example::

Predicate(“IconicDuo(Character,Character)”, [[“Harry”,”Sally”], [“Bonny”,”Clyde”]]

would result in::

“IconicDuo(Charachter,Character) = {(Harry,Sally); (Bonny,Clyde)}”

Type(name, enumeration, constructed_from=False, isa=None)

Adds a type. The type can be int or stringbased. The enumeration needs to be supplied as a list, or a tuple. As for right now, string should be supplied with extra quotation marks.

The int can be supplied as a list of ints or as a tuple of ints. A tuple can be used to set a range of values, and will be translated as such.

Example:

Type(Example, (0,10)) -> Example = {0..10} Type(Example, list(range(0,10))) -> Example = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}

Parameters:

• name – the name of the Type
• enumeration – a one-dimensional list containing all possible

values of the Type. :param constructed_from: allows the Type to have ‘constructed_from’. TODO: Add this! :type name: str :type enumeration: list of int, string, float, … :type constructed_from: list of int, string, float, … :returns: IDPIntType or IDPType object

append(p)

Adds objects into the idpobjecst dictionary. These objects are:

• IDPPredicate, IDPUnknownPredicate
• IDPType, IDPInt
• IDPUnknownFunction, IDPEnumeratedFunction
• Function
• IDPGeneratedFunction
• IDPGeneratedPartialFunction
• IDPDefinition

Parameters:p (see above) – one of the above listed objects

check_sat()

Checks the satisfiability of the current IDP system.

check_sat_script()

Generates .idp file to check if the model is satisfiable.

Returns:A script readable by IDP. Return type:str

customScript(main, term='')

Generates a .idp file with a custom main. Works by adding a custom Mainblock to the other blocks. Optionally, a term to minimize can also be added. The Term needs to be preformatted Term string.

Returns:A custom script readable by IDP. Return type:str Raises:ValueError when the supplied term isn’t str

forget(old)

Delete an object from the idpobjects dictionary, and also from the wanted list if it was found there.

Parameters:old (an idpobject) – the idpobject to remove

init_options()

This method initialises all the options. They all start as None-values (safe for xsb and nbrmodels)

know(p)

Adds objects into the idpobject dictionary, and returns the object. These objects are:

• IDPPredicate, IDPUnknownPredicate
• IDPType, IDPInt
• IDPUnknownFunction, IDPEnumeratedFunction
• Function
• IDPGeneratedFunction
• IDPGeneratedPartialFunction
• IDPDefinition

Parameters:p (see above) – one of the above listed objects Returns:the object which was added to the dictionary

minimize(term, ssh=False, remote_idp_location=None, known_hosts_location=None, address=None, username=None, password=None)

Run the IDPsystem’s minimize and read its output. Works by piping to input to the IDP executable, and reading the output. Once this command has been run, the idp object should have new attributes in the same name of the constants/functions/relations/…, which should be readable in Python.

For example, a function called ‘Group’ should now be accessible by fetching the ‘Group’ attribute of the IDP object.

Parameters:

• term (bool) – the content of the term block, in IDP-form
• ssh – Can be used to run IDP over SSH

minimize_script(termblock)

Generates the script for basic minimization of a term. Works by adding a Term and a Main block to the other blocks. More specifically: a Main block containing the ‘minimize’ function. The Term block needs to be called ‘t’ and needs to use Vocabulary ‘V’ for it to work. By default a voc is always called V, so this is no problem.

Returns:A script readable by IDP for term minimization. Return type:str

modelexpand_script()

Generates the IDP-ready script for basic modelgeneration. Works by adding a Main block to all the other blocks. More specifically: a Main block containing the ‘generate’ IDP function.

Returns:A fullfledged IDP-readable script for modelgeneration. Return type:str

printunsatcore(timeout=0)

Call printunsatcore on the IDP object and return the unsat core. The call will end early after timeout seconds. (default: 0 = no timeout)

refresh()

Run the IDPsystem’s modelgeneration and read its output. Works by piping to input to the IDP executable, and reading the output. Once this command has been run, the idp object should have new attributes in the same name of the constants/functions/relations/…, which should be readable in Python.

For example, a function called ‘Group’ should now be accessible by fetching the ‘Group’ attribute of the IDP object. :Example:

grouparray = IDP.Group

static split_func_name(func_name)

Static method to split a function. Splits a Function name into two parts: the function, and the Type it maps on (the return_type).

Example:Foo(bar): baz would be split in “Foo(bar)” and “baz”.

static split_pred_name(pred_name)

Static method to split a predicate. Splits a predicate in two parts: the name of the predicate, and the type it holds.

Example:Foo(bar,baz) would be split in “Foo” and “[bar, baz]”

class pyidp3.typedIDP.Structure(name, voc)

A class for the Structure block, which is a subclass of Block. It adds the voc-attribute, and overwrites the header.

Inherits Block:

header()

Generates the specific header for a Structure.

Returns:the header, in IDP-form. Return type:str

class pyidp3.typedIDP.Term(term, voc='V')

A class for the Term block, which is a subclass of Block. It adds a term attribute, (a string containing the content of the Term block) and overwrites the header and the content methods.

content()

Term has a specific content, which is just the self.term (cause it’s already in IDP format). This is between two linefeeds.

Returns:the termcontent as it was initialized (self.term) Return type:str

header()

The specific header for a Term.

Returns:the Termblock turned into IDP format Return type:str

class pyidp3.typedIDP.Theory(name, voc)

A class for the Theory block, which is a subclass of Block. It changes the voc-attribute, and overwrites the header.

Inherits Block:

header()

The specific header for a Theory, the only variables are the Theoryname and the Vocabularyname.

For Theory T and Vocabulary V, the string looks like:

‘theory T: V ‘

Returns:the header of the Theory, in IDP-form. Return type:str

class pyidp3.typedIDP.Vocabulary(name)

A class for the Vocabulary block, which is a subclass of Block. It overwrites the header. Uses Block’s __init__ method.

header()

Generates the specific header for a Vocabulary.

Returns:the header, in IDP-form. Return type:str

pyidp3.typedIDP.subclasses(cls)

TODO: describe

The idpobjects submodule:

This submodule contains an object for every kind of idp object.

This file contains all the IDP objects.

class pyidp3.idpobjects.IDPConstraint(idp, formula)

class pyidp3.idpobjects.IDPConstructedType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPDefinition(idp, rule_list)

class pyidp3.idpobjects.IDPEmptyConstantFunction(idp, name, args, rt, partial=False)

class pyidp3.idpobjects.IDPEnumeratedFunction(idp, name, args, rt, enum, partial=False, ct=False)

class pyidp3.idpobjects.IDPEnumeratedObject(idp, name, typing, enum, ct)

class pyidp3.idpobjects.IDPEnumeratedPredicate(idp, name, typing, enum, ct)

add(x)

Add an element.

discard(x)

Remove an element. Do not raise an exception if absent.

class pyidp3.idpobjects.IDPFloatRangeType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPFloatType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPFunction(idp, name, types, return_type, partial=False, ct=False)

class pyidp3.idpobjects.IDPGeneratedFunction(idp, name, args, rt, impl, partial=False)

class pyidp3.idpobjects.IDPGeneratedObject(*args)

class pyidp3.idpobjects.IDPGeneratedPredicate(*args)

class pyidp3.idpobjects.IDPIntRangeType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPIntType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPObject(idp)

‘Abstract’ class for all the IDP objects. Initialises idp.

class pyidp3.idpobjects.IDPPredicate(idp, name, typing, ct=False)

class pyidp3.idpobjects.IDPRule(idp, head_pred, vars_, body)

class pyidp3.idpobjects.IDPRuleStr(idp, string)

class pyidp3.idpobjects.IDPSpecialType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPTheoryObject(idp)

class pyidp3.idpobjects.IDPType(idp, name, enum, ct=False)

class pyidp3.idpobjects.IDPUnknownFunction(idp, name, args, rt, partial=False, ct=False)

class pyidp3.idpobjects.IDPUnknownObject(idp, name, typing, enum, ct)

class pyidp3.idpobjects.IDPUnknownPredicate(idp, name, types)

class pyidp3.idpobjects.IDPValueConstantFunction(idp, name, args, rt, enumeration, partial=False)

class pyidp3.idpobjects.IDPVocabularyObject(idp, name, typing, ct=False)

Abstract class for all the objects that appear in a vocabulary.

in_theory()

Doesn’t show up in a theory, so returns empty string.

The idp_py_syntax submodule:

This submodule contains everything needed to convert Pythonic data to IDP. This is something that was support by the original Pyidp, but is no longer supported by Pyidp3. The code might still work, it’s just not being worked on.

class pyidp3.idp_py_syntax.FormulaBuilder

generic_visit(node)

Called if no explicit visitor function exists for a node.

The idp_parse_out submodule:

This submodule contains all the code necessary to read IDP output and convert it to Python.