picos.glyphs

PICOS internally uses this module to produce string representations for the algebraic expressions that you create. The function-like objects that are used to build such strings are called “glyphs” and are instanciated by this module following the singleton pattern. As a result, you can modify the glyph objects listed below to influence how PICOS will format future strings, for example to disable use of unicode symbols that your console does not suppport or to adapt PICOS’ output to the rest of your application.

Here’s an example of first swapping the entire character set to display expressions using only Latin-1 characters, and then modifying a single glyph to our liking:

>>> import picos
>>> X = picos.new_problem().add_variable("X", (2,2), "symmetric")
>>> print(X >> 0)
X ≽ 0
>>> picos.glyphs.latin1()
>>> print(X >> 0)
X » 0
>>> picos.glyphs.psdge.template = "{} - {} is psd"
>>> print(X >> 0)
X - 0 is psd

Note that glyphs understand some algebraic rules such as operator precedence and associativity. This is possible because strings produced by glyphs remember how they were created.

>>> one_plus_two = picos.glyphs.add(1, 2)
>>> one_plus_two
'1 + 2'
>>> one_plus_two.glyph.template, one_plus_two.operands
('{} + {}', (1, 2))
>>> picos.glyphs.add(one_plus_two, 3)
'1 + 2 + 3'
>>> picos.glyphs.sub(0, one_plus_two)
'0 - (1 + 2)'

The positive semidefinite glyph above does not yet know how to properly handle arguments with respect to the - symbol involved, but we can modify it further:

>>> print(X + X >> X + X)
X + X - X + X is psd
>>> # Use the same operator binding strength as regular substraction.
>>> picos.glyphs.psdge.order = picos.glyphs.sub.order
>>> print(X + X >> X + X)
X + X - (X + X) is psd

You can reset all glyphs to their initial state as follows:

>>> picos.glyphs.default()

Members

class picos.glyphs.Am(glyph)

Bases: picos.glyphs.Op

A math atom glyph.

class picos.glyphs.Br(glyph)

Bases: picos.glyphs.Op

A math operator glyph with enclosing brackets.

class picos.glyphs.Fn(glyph)

Bases: picos.glyphs.Op

A math operator glyph in function form.

class picos.glyphs.Gl(glyph)

Bases: object

The basic “glyph”, a wrapper for a format string that contains special symbols for building (algebraic) expressions.

Sublcasses are supposed to extend formatting routines, going beyond of what Python string formatting is capabale of. In particular, glyphs can be used to craft unambiguous algebraic expressions with the minimum amount of parenthesis.

rebuild()

If the template was created using other glyphs, rebuild it.

Returns:True if the template has changed.
reset()
update(new)
class picos.glyphs.GlStr(string, glyph, operands)

Bases: str

A string created from a glyph.

It has an additional glyph field pointing to the glyph that created it, and a operands field containing the values used to create it.

reglyphed()
Returns:A rebuilt version of the string using current glyphs.
glyph = None

The glyph used to create the string.

operands = None

The operands used to create the string.

class picos.glyphs.Op(glyph, order, assoc=False, closed=False)

Bases: picos.glyphs.Gl

The basic math operator glyph.

Parameters:
  • glyph (str) – A string format template denoting the symbols to be used.
  • order (int) – The operator’s position in the binding strength hierarchy. Operators with lower numbers have precedence (bind more strongly).
  • assoc (bool) – If this is True, then the operator is associative, so that parenthesis are always omitted around operands with an equal outer operator. Otherwise, (1) parenthesis are used around the right hand side operand of a binary operation of same binding strength and (2) around all operands of non-binary operations of same binding strength.
  • closed (bool) – If True, the operator already encloses the operands in some sort of brackets, so that no additional parenthesis are needed. For glyphs where only some operands are enclosed, this can be a list.
reset()
update(new)
class picos.glyphs.OpStr(string, glyph, operands)

Bases: picos.glyphs.GlStr

A string created from a math operator glyph.

class picos.glyphs.Rl(glyph)

Bases: picos.glyphs.Op

A math relation glyph.

class picos.glyphs.Tr(glyph)

Bases: picos.glyphs.Op

A math glyph in superscript/trailer form.

picos.glyphs.ascii()

Let PICOS create future string representations using only ASCII characters.

picos.glyphs.cleverAdd(left, right)

A wrapper around add that resorts to sub if the second operand was created by neg or is a negative number (string). In both cases the second operand is adjusted accordingly.

Example

>>> from picos.glyphs import neg, add, cleverAdd, matrix
>>> add("x", neg("y"))
'x + -y'
>>> cleverAdd("x", neg("y"))
'x - y'
>>> add("X", matrix(neg("y")))
'X + [-y]'
>>> cleverAdd("X", matrix(neg("y")))
'X - [y]'
>>> cleverAdd("X", matrix(-1.5))
'X - [1.5]'
picos.glyphs.cleverNeg(value)

A wrapper around neg that resorts to unnegating an already negated value.

Example

>>> from picos.glyphs import neg, cleverNeg, matrix
>>> neg("x")
'-x'
>>> neg(neg("x"))
'-(-x)'
>>> cleverNeg(neg("x"))
'x'
>>> neg(matrix(-1))
'-[-1]'
>>> cleverNeg(matrix(-1))
'[1]'
picos.glyphs.cleverSub(left, right)

A wrapper around sub that resorts to add if the second operand was created by neg or is a negative number(string). In both cases the second operand is adjusted accordingly.

Example

>>> from picos.glyphs import neg, sub, cleverSub, matrix
>>> sub("x", neg("y"))
'x - -y'
>>> cleverSub("x", neg("y"))
'x + y'
>>> sub("X", matrix(neg("y")))
'X - [-y]'
>>> cleverSub("X", matrix(neg("y")))
'X + [y]'
>>> cleverSub("X", matrix(-1.5))
'X + [1.5]'
picos.glyphs.colVectorize(*entries)
picos.glyphs.default(rebuildDerivedGlyphs=True)

Let PICOS create future string representations using unicode characters.

picos.glyphs.is_negated(value)

Checks if a value can be unnegated by unnegate.

picos.glyphs.latin1(rebuildDerivedGlyphs=True)

Let PICOS create future string representations using ISO 8859-1 characters.

picos.glyphs.makeFunction(*names)

Creates an ad-hoc composite function glyphs.

Example

>>> from picos.glyphs import makeFunction
>>> makeFunction("log", "sum", "exp")("x")
'log∘sum∘exp(x)'
picos.glyphs.matrixCat(left, right, horizontal=True)

A clever wrapper around matrix, horicat and vertcat.

Example

>>> from picos.glyphs import matrixCat
>>> Z = matrixCat("X", "Y")
>>> Z
'[X, Y]'
>>> matrixCat(Z, Z)
'[X, Y, X, Y]'
>>> matrixCat(Z, Z, horizontal = False)
'[X, Y; X, Y]'
picos.glyphs.rebuild()

Updates glyphs that are based upon other glyphs.

picos.glyphs.rowVectorize(*entries)
picos.glyphs.scalar(value)

This function mimics an operator glyph, but it returns a normal string (as opposed to an OpStr).

This is not realized as an atomic operator glyph to not increase the recursion depth of is_negated and unnegate unnecessarily.

Example

>>> from picos.glyphs import scalar
>>> str(1.0)
'1.0'
>>> scalar(1.0)
'1'
picos.glyphs.show(*args)
picos.glyphs.unicode(rebuildDerivedGlyphs=True)

Let PICOS create future string representations using unicode characters.

picos.glyphs.unnegate(value)

Unnegates a value in a sensible way, more precisely by recursing through a sequence of glyphs used to create the value and for which we can factor out negation, and negating the underlaying (numeric or string) value.

Raises:ValueError – When is_negated(value) returns False.
picos.glyphs.Diag = <picos.glyphs.Fn object>

Diagonal matrix glyph.

picos.glyphs.abs = <picos.glyphs.Br object>

Absolute value glyph.

picos.glyphs.add = <picos.glyphs.Op object>

Addition glyph.

picos.glyphs.closure = <picos.glyphs.Fn object>

Set closure glyph.

picos.glyphs.compose = <picos.glyphs.Gl object>

Function composition glyph.

picos.glyphs.conj = <picos.glyphs.Tr object>

Complex conugate glyph.

picos.glyphs.cubed = <picos.glyphs.Tr object>

Cubed value glyph.

picos.glyphs.det = <picos.glyphs.Fn object>

Determinant glyph.

picos.glyphs.diag = <picos.glyphs.Fn object>

Diagonal vector glyph.

picos.glyphs.div = <picos.glyphs.Op object>

Division glyph.

picos.glyphs.dotp = <picos.glyphs.Br object>

Scalar product glyph.

picos.glyphs.element = <picos.glyphs.Rl object>

Set element glyph.

picos.glyphs.eq = <picos.glyphs.Rl object>

Equality glyph.

picos.glyphs.exp = <picos.glyphs.Fn object>

Exponentiation glyph.

picos.glyphs.forall = <picos.glyphs.Gl object>

Universal quantification glyph.

picos.glyphs.fromto = <picos.glyphs.Gl object>

Range glyph.

picos.glyphs.ge = <picos.glyphs.Rl object>

Greater or equal glyph.

picos.glyphs.gt = <picos.glyphs.Rl object>

Greater than glyph.

picos.glyphs.hadamard = <picos.glyphs.Op object>

Hadamard product glyph.

picos.glyphs.horicat = <picos.glyphs.Op object>

Horizontal concatenation glyph.

picos.glyphs.htransp = <picos.glyphs.Tr object>

Matrix hermitian transposition glyph.

picos.glyphs.idmatrix = <picos.glyphs.Am object>

Identity matrix glyph.

picos.glyphs.interval = <picos.glyphs.Gl object>

Interval glyph.

picos.glyphs.intrange = <picos.glyphs.Gl object>

Integer range glyph.

picos.glyphs.kron = <picos.glyphs.Op object>

Kronecker product glyph.

picos.glyphs.lambda_ = <picos.glyphs.Am object>

Lambda symbol glyph.

picos.glyphs.le = <picos.glyphs.Rl object>

Lesser or equal glyph.

picos.glyphs.log = <picos.glyphs.Fn object>

Logarithm glyph.

picos.glyphs.lt = <picos.glyphs.Rl object>

Lesser than glyph.

picos.glyphs.matrix = <picos.glyphs.Br object>

Matrix glyph.

picos.glyphs.max = <picos.glyphs.Fn object>

Maximum glyph.

picos.glyphs.min = <picos.glyphs.Fn object>

Minimum glyph.

picos.glyphs.mul = <picos.glyphs.Op object>

Multiplication glyph.

picos.glyphs.neg = <picos.glyphs.Op object>

Negation glyph.

picos.glyphs.norm = <picos.glyphs.Br object>

Norm glyph.

picos.glyphs.parenth = <picos.glyphs.Gl object>

Parenthesis glyph.

picos.glyphs.pnorm = <picos.glyphs.Op object>

p-Norm glyph.

picos.glyphs.power = <picos.glyphs.Tr object>

Power glyph.

picos.glyphs.pqnorm = <picos.glyphs.Op object>

pq-Norm glyph.

picos.glyphs.psdge = <picos.glyphs.Rl object>

Lesser or equal w.r.t. the p.s.d. cone glyph.

picos.glyphs.psdle = <picos.glyphs.Rl object>

Greater or equal w.r.t. the p.s.d. cone glyph.

picos.glyphs.ptrace = <picos.glyphs.Op object>

Matrix p-Trace glyph.

picos.glyphs.ptransp = <picos.glyphs.Tr object>

Matrix partial transposition glyph.

picos.glyphs.repr1 = <picos.glyphs.Gl object>

Representation glyph.

picos.glyphs.repr2 = <picos.glyphs.Gl object>

Long representation glyph.

picos.glyphs.sep = <picos.glyphs.Gl object>

Seperator glyph.

picos.glyphs.set = <picos.glyphs.Gl object>

Set glyph.

picos.glyphs.size = <picos.glyphs.Gl object>

Matrix size/shape glyph.

picos.glyphs.slice = <picos.glyphs.Op object>

Expression slicing glyph.

picos.glyphs.squared = <picos.glyphs.Tr object>

Squared value glyph.

picos.glyphs.sub = <picos.glyphs.Op object>

Substraction glyph.

picos.glyphs.sum = <picos.glyphs.Fn object>

Summation glyph.

picos.glyphs.trace = <picos.glyphs.Fn object>

Matrix trace glyph.

picos.glyphs.transp = <picos.glyphs.Tr object>

Matrix transposition glyph.

picos.glyphs.vertcat = <picos.glyphs.Op object>

Vertical concatenation glyph.