Config
Default values listed at the end of the page.
General settings for Pyoframe (for advanced users).
Accessible via pf.Config (see examples below).
Methods:
| Name | Description |
|---|---|
reset_defaults |
Resets all configuration options to their default values. |
Attributes:
| Name | Type | Description |
|---|---|---|
default_solver |
SUPPORTED_SOLVER_TYPES | _Solver | Literal['raise', 'auto']
|
The solver to use when Model is instantiated without specifying a solver. |
disable_extras_checks |
bool
|
When |
enable_is_duplicated_expression_safety_check |
bool
|
Setting for internal testing purposes only. |
float_to_str_precision |
int | None
|
Number of decimal places to use when displaying mathematical expressions. |
id_dtype |
The Polars data type to use for variable and constraint IDs. |
|
integer_tolerance |
float
|
Tolerance for checking if a floating point value is an integer. |
maintain_order |
bool
|
Whether the order of variables, constraints, and mathematical terms is to be identical across runs. |
print_max_terms |
int
|
Maximum number of terms to print in an expression before truncating it. |
print_polars_config |
Config
|
|
default_solver: SUPPORTED_SOLVER_TYPES | _Solver | Literal['raise', 'auto']
The solver to use when Model is instantiated without specifying a solver.
If auto, Pyoframe will try to use whichever solver is installed.
If raise, an exception will be raised when Model is instantiated without specifying a solver.
We recommend that users specify their solver when instantiating Model rather than relying on this option.
disable_extras_checks: bool
When True, improves performance by skipping checks for extra values (not recommended).
When True, checks for extra values are disabled which effectively means that all expressions
are treated as if they contained .keep_extras()
(unless .drop_extras() was applied).
Warning
This might improve performance, but it will suppress the errors that alert you of unexpected behaviors (learn more). Only consider enabling after you have thoroughly tested your code.
Examples:
>>> import polars as pl
>>> population = pl.DataFrame(
... {
... "city": ["Toronto", "Vancouver", "Montreal"],
... "pop": [2_731_571, 631_486, 1_704_694],
... }
... ).to_expr()
>>> population_influx = pl.DataFrame(
... {
... "city": ["Toronto", "Vancouver", "Montreal"],
... "influx": [100_000, 50_000, None],
... }
... ).to_expr()
Normally, an error warns users that the two expressions have conflicting labels:
>>> population + population_influx
Traceback (most recent call last):
...
pyoframe._constants.PyoframeError: Cannot add the two expressions below because expression 1 has extra labels.
Expression 1: pop
Expression 2: influx
Extra labels in expression 1:
┌──────────┐
│ city │
╞══════════╡
│ Montreal │
└──────────┘
Use .drop_extras() or .keep_extras() to indicate how the extra labels should be handled. Learn more at
https://bravos-power.github.io/pyoframe/latest/learn/concepts/addition
But if Config.disable_extras_checks = True, the error is suppressed and the sum is considered to be population.keep_extras() + population_influx.keep_extras():
>>> pf.Config.disable_extras_checks = True
>>> population + population_influx
<Expression height=3 terms=3 type=constant>
┌───────────┬────────────┐
│ city ┆ expression │
│ (3) ┆ │
╞═══════════╪════════════╡
│ Toronto ┆ 2831571 │
│ Vancouver ┆ 681486 │
│ Montreal ┆ 1704694 │
└───────────┴────────────┘
enable_is_duplicated_expression_safety_check: bool
Setting for internal testing purposes only.
When True, pyoframe checks that there are no bugs leading to duplicated terms in expressions.
float_to_str_precision: int | None
Number of decimal places to use when displaying mathematical expressions.
Examples:
id_dtype
The Polars data type to use for variable and constraint IDs.
Defaults to pl.UInt32 which should be ideal for most users.
Users with more than 4 billion variables or constraints can change this to pl.UInt64.
Users concerned with memory usage and with fewer than 65k variables or constraints can change this to pl.UInt16.
Warning
Changing this setting after creating a model will lead to errors. You should only change this setting before creating any models.
Examples:
An error is automatically raised if the number of variables or constraints exceeds the chosen data type:
>>> pf.Config.id_dtype = pl.UInt8
>>> m = pf.Model()
>>> big_set = pf.Set(x=range(2**8 + 1))
>>> m.X = pf.Variable()
>>> m.constraint = m.X.over("x") <= big_set
Traceback (most recent call last):
...
TypeError: Number of constraints exceeds the current data type (UInt8). Consider increasing the data type by changing Config.id_dtype.
>>> m.X_large = pf.Variable(big_set)
Traceback (most recent call last):
...
TypeError: Number of variables exceeds the current data type (UInt8). Consider increasing the data type by changing Config.id_dtype.
integer_tolerance: float
Tolerance for checking if a floating point value is an integer.
Info
For convenience, Pyoframe returns the solution of integer and binary variables as integers not floating point values. To do so, Pyoframe must convert the solver-provided floating point values to integers. To avoid unexpected rounding errors, Pyoframe uses this tolerance to check that the floating point result is an integer as expected. Overly tight tolerances can trigger unexpected errors. Setting the tolerance to zero disables the check.
maintain_order: bool
Whether the order of variables, constraints, and mathematical terms is to be identical across runs.
If False, performance is improved, but your results may vary every so slightly across runs
since numerical errors can accumulate differently when the order of operations changes.
print_max_terms: int
Maximum number of terms to print in an expression before truncating it.
Examples:
>>> pf.Config.print_max_terms = 3
>>> m = pf.Model()
>>> m.X = pf.Variable(pf.Set(x=range(100)), pf.Set(y=range(100)))
>>> m.X.sum("y")
<Expression height=100 terms=10000 type=linear>
┌───────┬───────────────────────────────┐
│ x ┆ expression │
│ (100) ┆ │
╞═══════╪═══════════════════════════════╡
│ 0 ┆ X[0,0] + X[0,1] + X[0,2] … │
│ 1 ┆ X[1,0] + X[1,1] + X[1,2] … │
│ 2 ┆ X[2,0] + X[2,1] + X[2,2] … │
│ 3 ┆ X[3,0] + X[3,1] + X[3,2] … │
│ 4 ┆ X[4,0] + X[4,1] + X[4,2] … │
│ … ┆ … │
│ 95 ┆ X[95,0] + X[95,1] + X[95,2] … │
│ 96 ┆ X[96,0] + X[96,1] + X[96,2] … │
│ 97 ┆ X[97,0] + X[97,1] + X[97,2] … │
│ 98 ┆ X[98,0] + X[98,1] + X[98,2] … │
│ 99 ┆ X[99,0] + X[99,1] + X[99,2] … │
└───────┴───────────────────────────────┘
>>> m.X.sum()
<Expression terms=10000 type=linear>
X[0,0] + X[0,1] + X[0,2] …
print_polars_config: pl.Config
polars.Config object to use when printing dimensioned Pyoframe objects.
Examples:
For example, to limit the number of rows printed in a table, use set_tbl_rows:
>>> pf.Config.print_polars_config.set_tbl_rows(5)
<class 'polars.config.Config'>
>>> m = pf.Model()
>>> m.X = pf.Variable(pf.Set(x=range(100)))
>>> m.X
<Variable 'X' height=100>
┌───────┬──────────┐
│ x ┆ variable │
│ (100) ┆ │
╞═══════╪══════════╡
│ 0 ┆ X[0] │
│ 1 ┆ X[1] │
│ 2 ┆ X[2] │
│ … ┆ … │
│ 98 ┆ X[98] │
│ 99 ┆ X[99] │
└───────┴──────────┘
reset_defaults()
Resets all configuration options to their default values.
Examples:
>>> pf.Config.disable_extras_checks
False
>>> pf.Config.disable_extras_checks = True
>>> pf.Config.disable_extras_checks
True
>>> pf.Config.reset_defaults()
>>> pf.Config.disable_extras_checks
False
Comments