Kiwisolver

https://kiwisolver.readthedocs.io/en/latest/
Admin
Kiwisolver is an efficient C++ implementation of the Cassowary constraint solving algorithm with...
Tokens:4,151
Snippets:59
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Kiwisolver via PIP

Source: https://kiwisolver.readthedocs.io/en/latest/basis/installation.html

Install pre-compiled wheels using the standard PIP package manager.

```bash
$ pip install kiwisolver
```

--------------------------------

### Verify Kiwisolver installation

Source: https://kiwisolver.readthedocs.io/en/latest/basis/installation.html

Test the installation by importing the library in a Python environment.

```python
import kiwisolver
```

--------------------------------

### Install Kiwisolver via Conda

Source: https://kiwisolver.readthedocs.io/en/latest/basis/installation.html

Use these commands to install Kiwisolver from the default or conda-forge channels.

```bash
$ conda install kiwisolver

$ conda install kiwisolver -c conda-forge
```

--------------------------------

### Solver state dump output

Source: https://kiwisolver.readthedocs.io/en/latest/basis/solver_internals.html

Example of the text representation produced by the solver's dump or dumps methods.

```text
Objective
---------
-2 + 2 * e2 + 1 * s8 + -2 * s10

Tableau
-------
v1 | 1 + 1 * s10
e3 | -1 + 1 * e2 + -1 * s10
v4 | -1 + -1 * d5 + -1 * s10
s6 | -2 + -1 * s10
e9 | -1 + 1 * s8 + -1 * s10

Infeasible
----------
e3
e9

Variables
---------
bar = v1
foo = v4

Edit Variables
--------------
bar

Constraints
-----------
1 * bar + -0 >= 0  | strength = 1
1 * bar + 1 <= 0  | strength = 1.001e+09
1 * foo + 1 * bar + 0 == 0  | strength = 1.001e+09
1 * bar + 0 == 0  | strength = 1
```

--------------------------------

### Ineffective strength differentiation

Source: https://kiwisolver.readthedocs.io/en/latest/basis/solver_internals.html

Example of strength definitions that are too similar to produce useful results.

```Python
weak1 = strength.create(0, 0, 1)
weak2 = strength.create(0, 0, 2)
weak3 = strength.create(0, 0, 3)
```

--------------------------------

### Compile Kiwisolver from source

Source: https://kiwisolver.readthedocs.io/en/latest/basis/installation.html

Build the package from the local directory using PIP.

```bash
$ pip install .
```

--------------------------------

### Add constraints to solver

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Initialize a Solver instance and add the defined constraints to it.

```python
from kiwisolver import Solver

solver = Solver()

for cn in constraints:
    solver.addConstraint(cn)
```

```cpp
Solver solver;

for(auto& constraint : constraints)
{
    solver.addConstraint(constraint);
}
```

--------------------------------

### Set macOS deployment target

Source: https://kiwisolver.readthedocs.io/en/latest/basis/installation.html

Required for macOS Mojave users to ensure the compiler uses the correct C++ standard library.

```bash
$ export MACOSX_DEPLOYMENT_TARGET=10.10
```

--------------------------------

### Create custom strengths

Source: https://kiwisolver.readthedocs.io/en/latest/basis/solver_internals.html

Define custom constraint strengths using the strength creation API in Python and C++.

```Python
from kiwisolver import strength

my_strength = strength.create(1, 1, 1)
my_strength2 = strength.create(1, 1, 1, 2)
```

```C++
double my_strength = strength::create(1, 1, 1);
double my_strength = strength::create(1, 1, 1, 2);
```

--------------------------------

### Update variables after suggestion

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Suggest a new value for a variable and synchronize the solver state to update all dependent variables.

```python
solver.suggestValue(xm, 90)
solver.updateVariables()
print(xm.value(), x1.value(), x2.value())
```

```cpp
solver.suggestValue(xm, 90);
solver.updateVariables();
std::cout << xm.value() << ", " << x1.value() << ", " << x2.value();
```

--------------------------------

### Define variables

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Create Variable objects to represent values the solver will determine. Naming variables is recommended for better error messages.

```python
from kiwisolver import Variable

x1 = Variable('x1')
x2 = Variable('x2')
xm = Variable('xm')
```

```cpp
#include <kiwi/kiwi.h>

using namespace kiwi

Variable x1("x1");
Variable x2("x2");
Variable xm("xm");
```

--------------------------------

### kiwisolver.exceptions

Source: https://kiwisolver.readthedocs.io/en/latest/_modules/kiwisolver/exceptions.html

This section details the custom exceptions defined within the kiwisolver library.

```APIDOC
## Exception: BadRequiredStrength

### Description
Raised when a constraint with a required strength is invalid.

### Method
N/A (Exception Class)

### Endpoint
N/A (Exception Class)

## Exception: DuplicateConstraint

### Description
Raised when attempting to add a constraint that already exists.

### Method
N/A (Exception Class)

### Endpoint
N/A (Exception Class)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## Exception: DuplicateEditVariable

### Description
Raised when attempting to add an edit variable that already exists.

### Method
N/A (Exception Class)

### Endpoint
N/A (Exception Class)

## Exception: UnknownConstraint

### Description
Raised when a constraint is referenced that is not known to the solver.

### Method
N/A (Exception Class)

### Endpoint
N/A (Exception Class)

## Exception: UnknownEditVariable

### Description
Raised when an edit variable is referenced that is not known to the solver.

### Method
N/A (Exception Class)

### Endpoint
N/A (Exception Class)

## Exception: UnsatisfiableConstraint

### Description
Raised when a constraint cannot be satisfied by the solver.

### Method
N/A (Exception Class)

### Endpoint
N/A (Exception Class)
```

--------------------------------

### Define kiwisolver exception classes

Source: https://kiwisolver.readthedocs.io/en/latest/_modules/kiwisolver/exceptions.html

Custom exception classes for handling constraint and variable errors in the kiwisolver library.

```python
# --------------------------------------------------------------------------------------
# Copyright (c) 2023-2024, Nucleic Development Team.
#
# Distributed under the terms of the Modified BSD License.
#
# The full license is in the file LICENSE, distributed with this software.
# --------------------------------------------------------------------------------------
"""Kiwi exceptions.

Imported by the kiwisolver C extension.

"""




[docs]
class BadRequiredStrength(Exception):
    pass




[docs]
class DuplicateConstraint(Exception):
    __slots__ = ("constraint",)

    def __init__(self, constraint):
        self.constraint = constraint




[docs]
class DuplicateEditVariable(Exception):
    __slots__ = ("edit_variable",)

    def __init__(self, edit_variable):
        self.edit_variable = edit_variable




[docs]
class UnknownConstraint(Exception):
    __slots__ = ("constraint",)

    def __init__(self, constraint):
        self.constraint = constraint




[docs]
class UnknownEditVariable(Exception):
    __slots__ = ("edit_variable",)

    def __init__(self, edit_variable):
        self.edit_variable = edit_variable




[docs]
class UnsatisfiableConstraint(Exception):
    __slots__ = ("constraint",)

    def __init__(self, constraint):
        self.constraint = constraint
```

--------------------------------

### Apply weak constraint strength

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Assigns a weak strength to a constraint, allowing the solver to satisfy it on a best-effort basis.

```python
solver.addConstraint((x1 == 40) | "weak")
```

```cpp
solver.addConstraint(x1 == 40 | strength::weak);
```

--------------------------------

### Default strength definitions

Source: https://kiwisolver.readthedocs.io/en/latest/basis/solver_internals.html

The default strength values provided by the Kiwi library.

```Python
weak = strength.create(0, 0, 1)
medium = strength.create(0, 1, 0)
strong = strength.create(1, 0, 0)
required = strength.create(1000, 1000, 1000)
```

--------------------------------

### Suggest value for edit variable

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Provides a new value for a previously registered edit variable to update the solver's solution.

```python
solver.suggestValue(xm, 60)
```

```cpp
solver.suggestValue(xm, 60);
```

--------------------------------

### Define constraints

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Define a set of equalities or inequalities to be satisfied by the solver.

```python
constraints = [x1 >= 0, x2 <= 100, x2 >= x1 + 10, xm == (x1 + x2) / 2]
```

```cpp
Constraint constraints[] = { Constraint {x1 >= 0},
                             Constraint {x2 <= 100},
                             Constraint {x2 >= x1 + 20},
                             Constraint {xm == (x1 + x2) / 2}
                            };
```

--------------------------------

### Solver Class

Source: https://kiwisolver.readthedocs.io/en/latest/api/python.html

The Solver class is the primary interface for managing constraints and edit variables to solve linear systems.

```APIDOC
## Solver

### Description
The Solver class manages the collection of constraints and edit variables. It provides methods to add, remove, and update constraints and variables, as well as suggest values for edit variables.

### Methods
- **addConstraint(constraint)**: Add a constraint to the solver.
- **addEditVariable(variable, strength)**: Add an edit variable to the solver.
- **dump()**: Dump a representation of the solver internals to stdout.
- **dumps()**: Dump a representation of the solver internals to a string.
- **hasConstraint(constraint)**: Check whether the solver contains a constraint.
- **hasEditVariable(variable)**: Check whether the solver contains an edit variable.
- **removeConstraint(constraint)**: Remove a constraint from the solver.
- **removeEditVariable(variable)**: Remove an edit variable from the solver.
- **reset()**: Reset the solver to the initial empty starting condition.
- **suggestValue(variable, value)**: Suggest a desired value for an edit variable.
- **updateVariables()**: Update the values of the solver variables.
```

--------------------------------

### Constraint Class

Source: https://kiwisolver.readthedocs.io/en/latest/api/python.html

Represents a constraint applied to variables.

```APIDOC
## Constraint

### Description
Represents a constraint that can be added to a solver.

### Methods
- **expression()**: Get the expression object for the constraint.
- **op()**: Get the relational operator for the constraint.
- **strength()**: Get the strength for the constraint.
- **violated()**: Return whether or not the constraint was violated during the last solver pass.
```

--------------------------------

### Variable Class

Source: https://kiwisolver.readthedocs.io/en/latest/api/python.html

Represents a variable within the Kiwisolver system.

```APIDOC
## Variable

### Description
Represents a variable that can be used in expressions and constraints.

### Methods
- **context()**: Get the context object associated with the variable.
- **name()**: Get the name of the variable.
- **setContext(context)**: Set the context object associated with the variable.
- **setName(name)**: Set the name of the variable.
- **value()**: Get the current value of the variable.
```

--------------------------------

### Add edit variable

Source: https://kiwisolver.readthedocs.io/en/latest/basis/basic_systems.html

Registers a variable as editable with a specified strength, enabling the solver to accept suggested values for it.

```python
solver.addEditVariable(xm, 'strong')
```

```cpp
solver.addEditVariable(xm, strength::strong);
```
Tokens:
Raw