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 0x7f8d8ff05220>,
 <picos.glyphs.Fn object at 0x7f8d8ff058b0>,
 <picos.glyphs.Fn object at 0x7f8d8ff05d00>,
 <picos.glyphs.Fn object at 0x7f8d8ff05b20>,
 <picos.glyphs.Fn object at 0x7f8d8ff05d60>,
 <picos.glyphs.Fn object...

picos.glyphs.abs¶

Absolute value glyph.

Default value

<picos.glyphs.Br object at 0x7f8d8ff052e0>

picos.glyphs.add¶

Addition glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff276d0>

picos.glyphs.affpart¶

Affine part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27040>

picos.glyphs.and_¶

Logical and glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df7ad60>

picos.glyphs.bcasted¶

Broadcasted glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27340>

picos.glyphs.blinpart¶

Bilinear part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27100>

picos.glyphs.closure¶

Set closure glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d9df34be0>

picos.glyphs.comma¶

Seperated by comma glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df346d0>

picos.glyphs.compose¶

Function composition glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34730>

picos.glyphs.compsep¶

Compact seperator glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df343d0>

picos.glyphs.conj¶

Complex conugate glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05f40>

picos.glyphs.cstpart¶

Constant part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff271c0>

picos.glyphs.cubed¶

Cubed value glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27a90>

picos.glyphs.desvec¶

Symmetric de-vectorization glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05ca0>

picos.glyphs.det¶

Determinant glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05e20>

picos.glyphs.diag¶

Diagonal matrix glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05d60>

picos.glyphs.div¶

Division glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff278b0>

picos.glyphs.dotp¶

Scalar product glyph.

Default value

<picos.glyphs.Br object at 0x7f8d8ff05280>

picos.glyphs.element¶

Set element glyph.

Default value

<picos.glyphs.Rl object at 0x7f8d8ff27eb0>

picos.glyphs.eq¶

Equality glyph.

Default value

<picos.glyphs.Rl object at 0x7f8d8ff27f40>

picos.glyphs.exp¶

Exponentiation glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05a60>

picos.glyphs.exparg¶

Expected value glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27670>

picos.glyphs.expected¶

Epected value glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff274c0>

picos.glyphs.forall¶

Universal quantification glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df7aac0>

picos.glyphs.fromto¶

Range glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df7a7c0>

picos.glyphs.frozen¶

Frozen mutables glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27220>

picos.glyphs.ge¶

Greater or equal glyph.

Default value

<picos.glyphs.Rl object at 0x7f8d8ff27fa0>

picos.glyphs.gt¶

Greater than glyph.

Default value

<picos.glyphs.Rl object at 0x7f8d8ff29040>

picos.glyphs.hadamard¶

Hadamard product glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27790>

picos.glyphs.horicat¶

Horizontal concatenation glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27e20>

picos.glyphs.htransp¶

Matrix hermitian transposition glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27d60>

picos.glyphs.idmatrix¶

Identity matrix glyph.

Default value

<picos.glyphs.Am object at 0x7f8d8ff05160>

picos.glyphs.imag¶

Imaginary part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05ee0>

picos.glyphs.index¶

Index glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27dc0>

picos.glyphs.infty¶

Infinity glyph.

Default value

<picos.glyphs.Am object at 0x7f8d8ff050d0>

picos.glyphs.interval¶

Interval glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34250>

picos.glyphs.intrange¶

Integer range glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df7aaf0>

picos.glyphs.inverse¶

Matrix inverse glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27c40>

picos.glyphs.kron¶

Kronecker product glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff277f0>

picos.glyphs.lambda_¶

Lambda symbol glyph.

Default value

<picos.glyphs.Am object at 0x7f8d8ff051c0>

picos.glyphs.le¶

Lesser or equal glyph.

Default value

<picos.glyphs.Rl object at 0x7f8d8ff290a0>

picos.glyphs.leadsto¶

Successorship glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df7ac40>

picos.glyphs.linpart¶

Linear part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff270a0>

picos.glyphs.log¶

Logarithm glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05ac0>

picos.glyphs.lt¶

Lesser than glyph.

Default value

<picos.glyphs.Rl object at 0x7f8d8ff29100>

picos.glyphs.maindiag¶

Main diagonal glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05dc0>

picos.glyphs.matrix¶

Matrix glyph.

Default value

<picos.glyphs.Br object at 0x7f8d8ff05220>

picos.glyphs.max¶

Maximum glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff059a0>

picos.glyphs.maxarg¶

The basic math operator glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff29220>

picos.glyphs.min¶

Minimum glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05a00>

picos.glyphs.minarg¶

The basic math operator glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff29250>

picos.glyphs.mul¶

Multiplication glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27850>

picos.glyphs.ncnorm¶

Nuclear Norm glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff05880>

picos.glyphs.ncstpart¶

Nonconstant part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27160>

picos.glyphs.neg¶

Negation glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27910>

picos.glyphs.norm¶

Norm glyph.

Default value

<picos.glyphs.Br object at 0x7f8d8ff05340>

picos.glyphs.or_¶

Logical or glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d8ff05070>

picos.glyphs.parenth¶

Parenthesis glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34a60>

picos.glyphs.plsmns¶

Plus/Minus glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff279a0>

picos.glyphs.pnorm¶

p-Norm glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff05490>

picos.glyphs.power¶

Power glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27a00>

picos.glyphs.pqnorm¶

pq-Norm glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff055e0>

picos.glyphs.probdist¶

Probability distribution glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27460>

picos.glyphs.prod¶

Product glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05940>

picos.glyphs.psdge¶

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

Default value

<picos.glyphs.Rl object at 0x7f8d8ff29160>

picos.glyphs.psdle¶

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

Default value

<picos.glyphs.Rl object at 0x7f8d8ff291c0>

picos.glyphs.ptrace¶

Matrix p-Trace glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27520>

picos.glyphs.ptrace_¶

Matrix partial trace glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27610>

picos.glyphs.ptransp¶

Matrix partial transposition glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27d00>

picos.glyphs.ptransp_¶

Matrix partial transposition glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff275b0>

picos.glyphs.quadpart¶

Quadratic part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05fa0>

picos.glyphs.real¶

Real part glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05e80>

picos.glyphs.repr1¶

Representation glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34970>

picos.glyphs.repr2¶

Long representation glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34a30>

picos.glyphs.reshaped¶

Column-major (Fortran) reshaped glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27280>

picos.glyphs.reshaprm¶

Row-major (C-order) reshaped glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff272e0>

picos.glyphs.sep¶

Seperator glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34400>

picos.glyphs.set¶

Set glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df346a0>

picos.glyphs.shortint¶

Shortened interval glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df7a550>

picos.glyphs.shuffled¶

Matrix reshuffling glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff27400>

picos.glyphs.size¶

Matrix size/shape glyph.

Default value

<picos.glyphs.Gl object at 0x7f8d9df34610>

picos.glyphs.slice¶

Expression slicing glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27550>

picos.glyphs.spnorm¶

Spectral Norm glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff05730>

picos.glyphs.sqrt¶

Square root glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff273a0>

picos.glyphs.squared¶

Squared value glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27b20>

picos.glyphs.sub¶

Substraction glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27730>

picos.glyphs.sum¶

Summation glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff058b0>

picos.glyphs.svec¶

Symmetric vectorization glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05c40>

picos.glyphs.trace¶

Matrix trace glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05d00>

picos.glyphs.transp¶

Matrix transposition glyph.

Default value

<picos.glyphs.Tr object at 0x7f8d8ff27ca0>

picos.glyphs.trilvec¶

Lower triangular vectorization glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05b80>

picos.glyphs.triuvec¶

Upper triangular vectorization glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05be0>

picos.glyphs.vec¶

Vectorization glyph.

Default value

<picos.glyphs.Fn object at 0x7f8d8ff05b20>

picos.glyphs.vertcat¶

Vertical concatenation glyph.

Default value

<picos.glyphs.Op object at 0x7f8d8ff27e50>

Fork me on GitLab