constrained

Constrained

JavaScript Constraint solver with automatic variable assignment and event emission on variable change.

Finds a feasible solution to a system of constraints and assign it to linked object properties. Based on cassowary.js, an implementation of the simplex algorithm (it can only handle linear continuous optimisation problems).

How to use

In a browser

Include Constrained's build in your html using either the minified library or the unminified version.

<script src="constraint.min.js"></script>

In Node.js

Install Constrained using npm install constrained, then require it:

var Constrained = require('constrained');

##API

The following example shows how to instantiate and solve a system with two variables, one constant and one constraint:

var myObject1 = { a: 0, b: 0 };
var myObject2 = { c: 100 };

// Instantiation of the system
var mySystem = new Constrained.System();

// Instantiation of the variables and the constant
mySystem.addVariable('x', myObject1, 'a'); // variable named x
mySystem.addVariable('y', myObject1, 'b'); // variable named y
mySystem.addConstant('c', myObject2, 'c'); // constant named c

// Definition of the system
mySystem.addConstraint('x + y = c');

// Solving the system to obtain a feasible solution
mySystem.resolve();

// Displaying the result
mySystem.log(); // x + y = 100

// Making sure that objects have been updated
console.log('(x, y) = (', myObject1.a, ',', myObject1.b, ')');

To change a constant's value:

// Changing the value of the property associated with c
myObject2.c = 25;

// Solving the system to obtain a new feasible solution
// that respect the new constant parameter
mySystem.resolve();

// Displaying the solution
mySystem.log(); // x + y = 25

// Making sure that objects have been updated
console.log('(x, y) = (', myObject1.a, ',', myObject1.b, ')'); 

To specify an objective to optimize:

// Bounding x
mySystem.addConstraint('x >= 0')
mySystem.minimize('x');

// Solving the system will now give an optimal
// solution to the optimization problem
mySystem.resolve();

// Displaying the solution
mySystem.log(); // x + y = 25, x minimized and >= 0

// Making sure that objects have been updated
console.log('(x, y) = (', myObject1.a, ',', myObject1.b, ')');

Possibility to chain function calls:

var mySystem = new Constrained.System()
	.addConstraint('- x1 - x2 + 2 * x3 <= -3')
	.addConstraint('- 4 * x1 - 2 * x2 + x3 <= -4')
	.addConstraint('x1 + x2 - 4 * x3 <= 2')
	.addConstraint('x1 >= 0')
	.addConstraint('x2 >= 0')
	.addConstraint('x3 >= 0')
	.maximize('- 4 * x1 - 2 * x2 + x3')
	.resolve();

mySystem.log();

// Fetching variable values
var x1 = mySystem.getValue('x1');
var x2 = mySystem.getValue('x2');
var x3 = mySystem.getValue('x3');
var z  = mySystem.getObjectiveValue();

console.log('(x1, x2, x3, z) = (', x1, ',', x2, ',', x3, ',', z, ')');

Possibility to define a system using the function API (for improved performance):

var Cst = Constrained;

var myObject1 = { x: 0 };
var myObject2 = { x: 0 };
var myObject3 = { x: 0 };

var mySystem = new Cst.System();

var myVariable1 = mySystem.addVariable('x1', myObject1, 'x').getVariable('x1');
var myVariable2 = mySystem.addVariable('x2', myObject2, 'x').getVariable('x2');
var myVariable3 = mySystem.addVariable('x3', myObject3, 'x').getVariable('x3');

var objective = Cst.plus(Cst.plus(Cst.times(-4, myVariable1), Cst.times(-2, myVariable2)), Cst.times(1, myVariable3));

var myConstraint1 = Cst.lowerThan(Cst.plus(Cst.plus(Cst.times(-1, myVariable1), Cst.times(-1, myVariable2)), Cst.times( 2, myVariable3)), -3);
var myConstraint2 = Cst.lowerThan(Cst.plus(Cst.plus(Cst.times(-4, myVariable1), Cst.times(-2, myVariable2)), Cst.times( 1, myVariable3)), -4);
var myConstraint3 = Cst.lowerThan(Cst.plus(Cst.plus(Cst.times( 1, myVariable1), Cst.times( 1, myVariable2)), Cst.times(-4, myVariable3)),  2);

var myConstraint4 = Cst.greaterThan(myVariable1, 0);
var myConstraint5 = Cst.greaterThan(myVariable2, 0);
var myConstraint6 = Cst.greaterThan(myVariable3, 0);

mySystem
	.addConstraint(myConstraint1)
	.addConstraint(myConstraint2)
	.addConstraint(myConstraint3)
	.addConstraint(myConstraint4)
	.addConstraint(myConstraint5)
	.addConstraint(myConstraint6)
	.maximize(objective)
	.resolve();

mySystem.log();

To add callbacks on variable or solution changes:

var mySquare = { width: 0, height: 0, area: 0 };
var myPerimeter = { length: 10 };

// Instantiation of the system
var mySystem = new Constrained.System()
	.addVariable('w', mySquare, 'width')
	.addVariable('h', mySquare, 'height')
	.addConstant('p', myPerimeter, 'length')
	.addConstraint('w = h')
	.addConstraint('w + h = p');

mySystem.getVariable('w').onChange(function(params, newValue, oldValue) {
	console.log('Width changed from', oldValue, 'to', newValue)	
});

mySystem.getVariable('h').onChange(function(params, newValue, oldValue) {
	console.log('Height changed from', oldValue, 'to', newValue)	
});

mySystem.onNewSolution(function(theSquare) {
	theSquare.area = theSquare.width * theSquare.height;
	console.log('New area is', theSquare.area);
}, mySquare);

// Solving the system to obtain a feasible solution
mySystem.resolve();

// Changing the value of the perimeter
myPerimeter.length = 20;

// Solving the system to obtain a new feasible solution
// that respect the new constant parameter
mySystem.resolve();

Note: Do not hesitate to post issues to suggest improvements