OPB (cpmpy.tools.io.opb)

OPB parser.

Currently only the restricted OPB PB24 format is supported (without WBO). More can be read about it here:

List of functions

load_opb

Loader for OPB (Pseudo-Boolean) format.

write_opb

Export a CPMpy model to the OPB (Pseudo-Boolean) format.
cpmpy.tools.io.opb.load_opb(opb: str | PathLike | TextIO, open: Callable = <built-in function open>) → Model[source]

Loader for OPB (Pseudo-Boolean) format. Loads an instance and returns its matching CPMpy model.

Based on PyPBLib’s example parser: https://hardlog.udl.cat/static/doc/pypblib/html/library/index.html#example-from-opb-to-cnf-file

Supports:

  • Linear and non-linear terms (e.g., -1 x1 x14 +2 x2)

  • Negated variables using ‘~’ (e.g., ~x5)

  • Minimisation objective

  • Comparison operators in constraints: ‘=’, ‘>=’

Parameters:

  • opb (str or os.PathLike or TextIO) –

    • A file path to an OPB file (optionally LZMA-compressed with .xz)

    • OR a string containing the OPB content directly

    • OR a TextIO object already open for reading

  • open (Callable) – callable to open the file for reading (default: builtin open). Use for decompression, e.g. lambda p: lzma.open(p, 'rt') for .opb.xz.

Returns:

The CPMpy model of the OPB instance.

Return type:

cp.Model

Example

>>> opb_text = '''
... * #variable= 5 #constraint= 2 #equal= 1 intsize= 64 #product= 5 sizeproduct= 13
... min: 2 x2 x3 +3 x4 ~x5 +2 ~x1 x2 +3 ~x1 x2 x3 ~x4 ~x5 ;
... 2 x2 x3 -1 x1 ~x3 = 5 ;
... '''
>>> model = read_opb(opb_text)
>>> print(model)
Model(...)

Notes

  • Comment lines starting with ‘*’ are ignored.

  • Only “min:” objectives are supported; “max:” is not recognized.

cpmpy.tools.io.opb.write_opb(model: Model, path: str | PathLike | None = None, encoding: str = 'auto', header: str | None = None, open: Callable = functools.partial(<built-in function open>, mode='w'), annotate_bool: BooleanEncodingAnnotator | None = None, naming: str = 'restricted') → str[source]

Export a CPMpy model to the OPB (Pseudo-Boolean) format.

This function transforms the given CPMpy model into OPB format, which is a standard textual format for representing Pseudo-Boolean (optimization) problems. The OPB file will contain a header specifying the number of variables and constraints, an objective function (optional), and a list of constraints using integer-weighted Boolean variables.

Parameters:

  • model (cp.Model) – The CPMpy model to export.

  • path (str or os.PathLike, optional) – The file path to write the OPB output to.

  • encoding (str, optional) – The encoding used for int2bool. Options: (“auto”, “direct”, “order”, “binary”).

  • header (str, optional) – Optional header text to add as OPB comments. If None, a default CPMpy header is created only when writing to path. Pass an empty string to skip adding a header.

  • open (callable) – Callable to open the file for writing (default: builtin open). Called as open(path). This mirrors the open= argument in loaders and allows custom compression or I/O (e.g. lambda p: lzma.open(p, 'wt')).

  • annotate_bool (BooleanEncodingAnnotator, optional) – encoding annotator, annotates boolean variables with names describing how they contribute to an encoded integer variable. Depending on the naming scheme, these names are written as comments or used directly as variable names.

  • naming (str) –

    how variables are named in the OPB output. One of:

    • "restricted" (default): competition-style x1, x2, … identifiers. Annotations, if provided, are written as comments.

    • "extended": allows arbitrary variable names, but wraps them in quotes.

    • "veripb": VeriPB-safe variable names.

Note

The "restricted" naming scheme is the most widely supported and compatible with most OPB parsers. The "extended" naming scheme is more flexible and allows arbitrary characters, but is not as widely supported. The "veripb" naming scheme follows the VeriPB convention;

  • start with an underscore or an ASCII letter (A-Z, a-z);

  • continue with A-Z, a-z, 0-9, or []{}_^ (square/curly brackets, underscore, caret);

  • be at least two characters long

  • contain no spaces

Any variable name that does not follow these rules will be rejected.

Returns:

The OPB string (as it is optionally written to a file).

Return type:

str

Format:

  • #variable= <n_vars> #constraint= <n_constraints>

min/max: <objective>; <constraint_1>; <constraint_2>; …

Example

>>> from cpmpy import *
>>> x = boolvar(shape=3)
>>> m = Model(x[0] + x[1] + x[2] >= 2)
>>> print(write_opb(m))