picos.glyphs

String templates used to print (algebraic) expressions.

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.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()

Classes

class picos.glyphs.Am(glyph)[source]

Bases: picos.glyphs.Op

A math atom glyph.

__init__(glyph)[source]

Construct an Am glyph.

Parameters

glyph (str) – The glyph’s format string template.

class picos.glyphs.Br(glyph)[source]

Bases: picos.glyphs.Op

A math operator glyph with enclosing brackets.

__init__(glyph)[source]

Construct a Br glyph.

Parameters

glyph (str) – The glyph’s format string template.

class picos.glyphs.Fn(glyph)[source]

Bases: picos.glyphs.Op

A math operator glyph in function form.

__init__(glyph)[source]

Construct a Fn glyph.

Parameters

glyph (str) – The glyph’s format string template.

class picos.glyphs.Gl(glyph)[source]

Bases: object

The basic “glyph”, an (algebraic) string formatting template.

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.

__init__(glyph)[source]

Construct a glyph.

Parameters

glyph (str) – The glyph’s format string template.

rebuild()[source]

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

Returns

True if the template has changed.

reset()[source]

Reset the glyph to its initial formatting template.

update(new)[source]

Change the glyph’s formatting template.

class picos.glyphs.GlStr(string, glyph, operands)[source]

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.

__init__(string, glyph, operands)[source]

Augment the Python string with metadata on its origin.

static __new__(cls, string, glyph, operands)[source]

Create a regular Python string.

reglyphed(replace={})[source]

Returns a rebuilt version of the string using current glyphs.

Parameters

replace (dict) – Replace leaf-node (non GlStr) strings with new strings. This can be used, for instance, to change the names of varaibles.

glyph

The glyph used to create the string.

operands

The operands used to create the string.

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

Bases: picos.glyphs.Gl

The basic math operator glyph.

__init__(glyph, order, assoc=False, closed=False)[source]

Construct a math operator glyph.

Parameters
  • glyph (str) – The glyph’s format string template.

  • order (int) – The operator’s position in the binding strength hierarchy. Operators with lower numbersbind 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 or list(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 specified per operand in the form of a list.

reset()[source]

Reset the glyph to its initial behavior.

update(new)[source]

Change the glyph’s behavior.

class picos.glyphs.OpStr(string, glyph, operands)[source]

Bases: picos.glyphs.GlStr

A string created from a math operator glyph.

class picos.glyphs.Rl(glyph)[source]

Bases: picos.glyphs.Op

A math relation glyph.

__init__(glyph)[source]

Construct a Rl glyph.

Parameters

glyph (str) – The glyph’s format string template.

class picos.glyphs.Tr(glyph)[source]

Bases: picos.glyphs.Op

A math glyph in superscript/trailer form.

__init__(glyph)[source]

Construct a Tr glyph.

Parameters

glyph (str) – The glyph’s format string template.

Functions

picos.glyphs.ascii()[source]

Let PICOS create future strings using only ASCII characters.

picos.glyphs.clever_add(left, right)[source]

Describe the addition of two values in a clever way.

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, clever_add, matrix
>>> add("x", neg("y"))
'x + -y'
>>> clever_add("x", neg("y"))
'x - y'
>>> add("X", matrix(neg("y")))
'X + [-y]'
>>> clever_add("X", matrix(neg("y")))
'X - [y]'
>>> clever_add("X", matrix(-1.5))
'X - [1.5]'
picos.glyphs.clever_div(left, right)[source]

Describe the division of one value by another in a clever way.

A wrapper around div that factors out identity factors.

picos.glyphs.clever_dotp(left, right, complexRHS, scalar=False)[source]

Describe an inner product in a clever way.

Parameters

complexRHS (bool) – Whether the right hand side is complex.

picos.glyphs.clever_mul(left, right)[source]

Describe the multiplocation of two values in a clever way.

A wrapper around mul that factors out identity factors.

picos.glyphs.clever_neg(value)[source]

Describe the negation of a value in a clever way.

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

Example

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

Describe the substraction of a value from another in a clever way.

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, clever_sub, matrix
>>> sub("x", neg("y"))
'x - -y'
>>> clever_sub("x", neg("y"))
'x + y'
>>> sub("X", matrix(neg("y")))
'X - [-y]'
>>> clever_sub("X", matrix(neg("y")))
'X + [y]'
>>> clever_sub("X", matrix(-1.5))
'X + [1.5]'
picos.glyphs.col_vectorize(*entries)[source]

Describe a column vector with the given symbolic entries.

picos.glyphs.default(rebuildDerivedGlyphs=True)

Let PICOS create future strings using only unicode characters.

picos.glyphs.free_var_name(string)[source]

Return a variable name not present in the given string.

picos.glyphs.from_glyph(string, theGlyph)[source]

Whether the given string was created by the given glyph.

picos.glyphs.is_negated(value)[source]

Check if a value can be unnegated by unnegate.

picos.glyphs.latin1(rebuildDerivedGlyphs=True)[source]

Let PICOS create future strings using only ISO 8859-1 characters.

picos.glyphs.make_function(*names)[source]

Create an ad-hoc composite function glyphs.

Example

>>> from picos.glyphs import make_function
>>> make_function("log", "sum", "exp")("x")
'log∘sum∘exp(x)'
picos.glyphs.matrix_cat(left, right, horizontal=True)[source]

Describe matrix concatenation in a clever way.

A wrapper around matrix, horicat and vertcat.

Example

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

Update glyphs that are based upon other glyphs.

picos.glyphs.row_vectorize(*entries)[source]

Describe a row vector with the given symbolic entries.

picos.glyphs.scalar(value)[source]

Format a scalar value.

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

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.shape(theShape)[source]

Describe a matrix shape that can contain wildcards.

A wrapper around size that takes just one argument (the shape) that may contain wildcards which are printed as '?'.

picos.glyphs.show(*args)[source]

Show output from all glyphs.

Parameters

args (list(str)) – Strings to use as glyph operands.

picos.glyphs.unicode(rebuildDerivedGlyphs=True)[source]

Let PICOS create future strings using only unicode characters.

picos.glyphs.unnegate(value)[source]

Unnegate a value, usually a glyph-created string, in a sensible way.

Unnegates a operator glyph created string or other 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 returns False.

Objects

picos.glyphs.CAN_FACTOR_OUT_NEGATION

Operator glyphs for which negation may be factored out.

Default value
(<picos.glyphs.Br object at 0x7f9e46be2ef0>,
 <picos.glyphs.Fn object at 0x7f9e46be2860>,
 <picos.glyphs.Fn object at 0x7f9e46be2410>,
 <picos.glyphs.Fn object at 0x7f9e46be25f0>,
 <picos.glyphs.Fn object at 0x7f9e46be23b0>,
 <picos.glyphs.Fn object...
picos.glyphs.abs

Absolute value glyph.

Default value
<picos.glyphs.Br object at 0x7f9e46be2e30>
picos.glyphs.add

Addition glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1a80>
picos.glyphs.affpart

Affine part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2110>
picos.glyphs.and_

Logical and glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be30d0>
picos.glyphs.bcasted

Broadcasted glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1e10>
picos.glyphs.blinpart

Bilinear part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2050>
picos.glyphs.closure

Set closure glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be3490>
picos.glyphs.comma

Seperated by comma glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3610>
picos.glyphs.compose

Function composition glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3550>
picos.glyphs.compsep

Compact seperator glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3670>
picos.glyphs.conj

Complex conugate glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be21d0>
picos.glyphs.cstpart

Constant part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1f90>
picos.glyphs.cubed

Cubed value glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be16c0>
picos.glyphs.desvec

Symmetric de-vectorization glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2470>
picos.glyphs.det

Determinant glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be22f0>
picos.glyphs.diag

Diagonal matrix glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be23b0>
picos.glyphs.div

Division glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be18a0>
picos.glyphs.dotp

Scalar product glyph.

Default value
<picos.glyphs.Br object at 0x7f9e46be2e90>
picos.glyphs.element

Set element glyph.

Default value
<picos.glyphs.Rl object at 0x7f9e46be12a0>
picos.glyphs.eq

Equality glyph.

Default value
<picos.glyphs.Rl object at 0x7f9e46be1210>
picos.glyphs.exp

Exponentiation glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be26b0>
picos.glyphs.exparg

Expected value glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1ae0>
picos.glyphs.expected

Epected value glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1c90>
picos.glyphs.forall

Universal quantification glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3190>
picos.glyphs.fromto

Range glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be33d0>
picos.glyphs.frozen

Frozen mutables glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1f30>
picos.glyphs.ge

Greater or equal glyph.

Default value
<picos.glyphs.Rl object at 0x7f9e46be11b0>
picos.glyphs.gt

Greater than glyph.

Default value
<picos.glyphs.Rl object at 0x7f9e46be1150>
picos.glyphs.hadamard

Hadamard product glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be19c0>
picos.glyphs.horicat

Horizontal concatenation glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1330>
picos.glyphs.htransp

Matrix hermitian transposition glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be13f0>
picos.glyphs.idmatrix

Identity matrix glyph.

Default value
<picos.glyphs.Am object at 0x7f9e46be2fb0>
picos.glyphs.imag

Imaginary part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2230>
picos.glyphs.index

Index glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be1390>
picos.glyphs.infty

Infinity glyph.

Default value
<picos.glyphs.Am object at 0x7f9e46be3010>
picos.glyphs.interval

Interval glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3430>
picos.glyphs.intrange

Integer range glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be32e0>
picos.glyphs.inverse

Matrix inverse glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be1510>
picos.glyphs.kron

Kronecker product glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1960>
picos.glyphs.lambda_

Lambda symbol glyph.

Default value
<picos.glyphs.Am object at 0x7f9e46be2f50>
picos.glyphs.le

Lesser or equal glyph.

Default value
<picos.glyphs.Rl object at 0x7f9e46be10f0>
picos.glyphs.leadsto

Successorship glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3130>
picos.glyphs.linpart

Linear part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be20b0>
picos.glyphs.log

Logarithm glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2650>
picos.glyphs.lt

Lesser than glyph.

Default value
<picos.glyphs.Rl object at 0x7f9e46be1090>
picos.glyphs.maindiag

Main diagonal glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2350>
picos.glyphs.matrix

Matrix glyph.

Default value
<picos.glyphs.Br object at 0x7f9e46be2ef0>
picos.glyphs.max

Maximum glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2770>
picos.glyphs.maxarg

The basic math operator glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be0f70>
picos.glyphs.min

Minimum glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2710>
picos.glyphs.minarg

The basic math operator glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be0f40>
picos.glyphs.mul

Multiplication glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1900>
picos.glyphs.ncnorm

Nuclear Norm glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be2890>
picos.glyphs.ncstpart

Nonconstant part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1ff0>
picos.glyphs.neg

Negation glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1840>
picos.glyphs.norm

Norm glyph.

Default value
<picos.glyphs.Br object at 0x7f9e46be2dd0>
picos.glyphs.or_

Logical or glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3070>
picos.glyphs.parenth

Parenthesis glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3730>
picos.glyphs.plsmns

Plus/Minus glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be17b0>
picos.glyphs.pnorm

p-Norm glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be2c80>
picos.glyphs.power

Power glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be1750>
picos.glyphs.pqnorm

pq-Norm glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be2b30>
picos.glyphs.probdist

Probability distribution glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1cf0>
picos.glyphs.prod

Product glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be27d0>
picos.glyphs.psdge

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

Default value
<picos.glyphs.Rl object at 0x7f9e46be1030>
picos.glyphs.psdle

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

Default value
<picos.glyphs.Rl object at 0x7f9e46be0fd0>
picos.glyphs.ptrace

Matrix p-Trace glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1c30>
picos.glyphs.ptrace_

Matrix partial trace glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1b40>
picos.glyphs.ptransp

Matrix partial transposition glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be1450>
picos.glyphs.ptransp_

Matrix partial transposition glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1ba0>
picos.glyphs.quadpart

Quadratic part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2170>
picos.glyphs.real

Real part glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2290>
picos.glyphs.repr1

Representation glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3880>
picos.glyphs.repr2

Long representation glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be3790>
picos.glyphs.reshaped

Column-major (Fortran) reshaped glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1ed0>
picos.glyphs.reshaprm

Row-major (C-order) reshaped glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1e70>
picos.glyphs.sep

Seperator glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be36d0>
picos.glyphs.set

Set glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be34f0>
picos.glyphs.shortint

Shortened interval glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be31f0>
picos.glyphs.shuffled

Matrix reshuffling glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1d50>
picos.glyphs.size

Matrix size/shape glyph.

Default value
<picos.glyphs.Gl object at 0x7f9e46be35b0>
picos.glyphs.slice

Expression slicing glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1c00>
picos.glyphs.spnorm

Spectral Norm glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be29e0>
picos.glyphs.sqrt

Square root glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be1db0>
picos.glyphs.squared

Squared value glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be1630>
picos.glyphs.sub

Substraction glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1a20>
picos.glyphs.sum

Summation glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2860>
picos.glyphs.svec

Symmetric vectorization glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be24d0>
picos.glyphs.trace

Matrix trace glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2410>
picos.glyphs.transp

Matrix transposition glyph.

Default value
<picos.glyphs.Tr object at 0x7f9e46be14b0>
picos.glyphs.trilvec

Lower triangular vectorization glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2590>
picos.glyphs.triuvec

Upper triangular vectorization glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be2530>
picos.glyphs.vec

Vectorization glyph.

Default value
<picos.glyphs.Fn object at 0x7f9e46be25f0>
picos.glyphs.vertcat

Vertical concatenation glyph.

Default value
<picos.glyphs.Op object at 0x7f9e46be1300>