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

Outline

Classes

Am

A math atom glyph.

Br

A math operator glyph with enclosing brackets.

Fn

A math operator glyph in function form.

Gl

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

GlStr

A string created from a glyph.

Op

The basic math operator glyph.

OpStr

A string created from a math operator glyph.

Rl

A math relation glyph.

Tr

A math glyph in superscript/trailer form.

Functions

ascii

Let PICOS create future strings using only ASCII characters.

clever_add

Describe the addition of two values in a clever way.

clever_div

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

clever_dotp

Describe an inner product in a clever way.

clever_mul

Describe the multiplocation of two values in a clever way.

clever_neg

Describe the negation of a value in a clever way.

clever_sub

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

col_vectorize

Describe a column vector with the given symbolic entries.

default

Let PICOS create future strings using only unicode characters.

free_var_name

Return a variable name not present in the given string.

from_glyph

Whether the given string was created by the given glyph.

is_negated

Check if a value can be unnegated by unnegate.

latin1

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

make_function

Create an ad-hoc composite function glyphs.

matrix_cat

Describe matrix concatenation in a clever way.

rebuild

Update glyphs that are based upon other glyphs.

row_vectorize

Describe a row vector with the given symbolic entries.

scalar

Format a scalar value.

shape

Describe a matrix shape that can contain wildcards.

show

Show output from all glyphs.

unicode

Let PICOS create future strings using only unicode characters.

unnegate

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

Classes

Am

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.

Br

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.

Fn

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.

Gl

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.

GlStr

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 = None

The glyph used to create the string.

operands = None

The operands used to create the string.

Op

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.

OpStr

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

Bases: picos.glyphs.GlStr

A string created from a math operator glyph.

Rl

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.

Tr

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

ascii

picos.glyphs.ascii()[source]

Let PICOS create future strings using only ASCII characters.

clever_add

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]'

clever_div

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.

clever_dotp

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.

clever_mul

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.

clever_neg

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]'

clever_sub

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]'

col_vectorize

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

Describe a column vector with the given symbolic entries.

default

picos.glyphs.default(rebuildDerivedGlyphs=True)

Let PICOS create future strings using only unicode characters.

free_var_name

picos.glyphs.free_var_name(string)[source]

Return a variable name not present in the given string.

from_glyph

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

Whether the given string was created by the given glyph.

is_negated

picos.glyphs.is_negated(value)[source]

Check if a value can be unnegated by unnegate.

latin1

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

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

make_function

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)'

matrix_cat

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]'

rebuild

picos.glyphs.rebuild()[source]

Update glyphs that are based upon other glyphs.

row_vectorize

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

Describe a row vector with the given symbolic entries.

scalar

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'

shape

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 '?'.

show

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

Show output from all glyphs.

Parameters

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

unicode

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

Let PICOS create future strings using only unicode characters.

unnegate

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.

Data

picos.glyphs.CAN_FACTOR_OUT_NEGATION

Operator glyphs for which negation may be factored out.

picos.glyphs.abs

Absolute value glyph.

picos.glyphs.add

Addition glyph.

picos.glyphs.affpart

Affine part glyph.

picos.glyphs.and_

Logical and glyph.

picos.glyphs.bcasted

Broadcasted glyph.

picos.glyphs.closure

Set closure glyph.

picos.glyphs.comma

Seperated by comma glyph.

picos.glyphs.compose

Function composition glyph.

picos.glyphs.compsep

Compact seperator glyph.

picos.glyphs.conj

Complex conugate glyph.

picos.glyphs.cstpart

Constant part glyph.

picos.glyphs.cubed

Cubed value glyph.

picos.glyphs.det

Determinant glyph.

picos.glyphs.diag

Diagonal matrix glyph.

picos.glyphs.div

Division glyph.

picos.glyphs.dotp

Scalar product glyph.

picos.glyphs.element

Set element glyph.

picos.glyphs.eq

Equality glyph.

picos.glyphs.exp

Exponentiation glyph.

picos.glyphs.forall

Universal quantification glyph.

picos.glyphs.fromto

Range glyph.

picos.glyphs.ge

Greater or equal glyph.

picos.glyphs.gt

Greater than glyph.

picos.glyphs.hadamard

Hadamard product glyph.

picos.glyphs.horicat

Horizontal concatenation glyph.

picos.glyphs.htransp

Matrix hermitian transposition glyph.

picos.glyphs.idmatrix

Identity matrix glyph.

picos.glyphs.imag

Imaginary part glyph.

picos.glyphs.infty

Infinity glyph.

picos.glyphs.interval

Interval glyph.

picos.glyphs.intrange

Integer range glyph.

picos.glyphs.kron

Kronecker product glyph.

picos.glyphs.lambda_

Lambda symbol glyph.

picos.glyphs.le

Lesser or equal glyph.

picos.glyphs.leadsto

Successorship glyph.

picos.glyphs.linpart

Linear part glyph.

picos.glyphs.log

Logarithm glyph.

picos.glyphs.lt

Lesser than glyph.

picos.glyphs.maindiag

Main diagonal glyph.

picos.glyphs.matrix

Matrix glyph.

picos.glyphs.max

Maximum glyph.

picos.glyphs.min

Minimum glyph.

picos.glyphs.mul

Multiplication glyph.

picos.glyphs.ncnorm

Nuclear Norm glyph.

picos.glyphs.neg

Negation glyph.

picos.glyphs.norm

Norm glyph.

picos.glyphs.or_

Logical or glyph.

picos.glyphs.parenth

Parenthesis glyph.

picos.glyphs.plsmns

Plus/Minus glyph.

picos.glyphs.pnorm

p-Norm glyph.

picos.glyphs.power

Power glyph.

picos.glyphs.pqnorm

pq-Norm glyph.

picos.glyphs.psdge

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

picos.glyphs.psdle

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

picos.glyphs.ptrace

Matrix p-Trace glyph.

picos.glyphs.ptrace_

Matrix partial trace glyph.

picos.glyphs.ptransp

Matrix partial transposition glyph.

picos.glyphs.ptransp_

Matrix partial transposition glyph.

picos.glyphs.quadpart

Quadratic part glyph.

picos.glyphs.real

Real part glyph.

picos.glyphs.repr1

Representation glyph.

picos.glyphs.repr2

Long representation glyph.

picos.glyphs.reshaped

Reshaped glyph.

picos.glyphs.sep

Seperator glyph.

picos.glyphs.set

Set glyph.

picos.glyphs.shortint

Shortened interval glyph.

picos.glyphs.size

Matrix size/shape glyph.

picos.glyphs.slice

Expression slicing glyph.

picos.glyphs.spnorm

Spectral Norm glyph.

picos.glyphs.sqrt

Square root glyph.

picos.glyphs.squared

Squared value glyph.

picos.glyphs.sub

Substraction glyph.

picos.glyphs.sum

Summation glyph.

picos.glyphs.trace

Matrix trace glyph.

picos.glyphs.transp

Matrix transposition glyph.

picos.glyphs.trilvec

Lower triangular vectorization glyph.

picos.glyphs.triuvec

Upper triangular vectorization glyph.

picos.glyphs.value

Value of expression glyph.

picos.glyphs.vec

Vectorization glyph.

picos.glyphs.vertcat

Vertical concatenation glyph.