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.
- class picos.glyphs.Br(glyph)[source]¶
Bases:
picos.glyphs.Op
A math operator glyph with enclosing brackets.
- class picos.glyphs.Fn(glyph)[source]¶
Bases:
picos.glyphs.Op
A math operator glyph in function form.
- 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.
- 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 aoperands
field containing the values used to create it.- 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.
- 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.
- class picos.glyphs.Tr(glyph)[source]¶
Bases:
picos.glyphs.Op
A math glyph in superscript/trailer form.
Functions
- picos.glyphs.clever_add(left, right)[source]¶
Describe the addition of two values in a clever way.
A wrapper around
add
that resorts tosub
if the second operand was created byneg
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 toadd
if the second operand was created byneg
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.from_glyph(string, theGlyph)[source]¶
Whether the given string was created by the given glyph.
- 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
andvertcat
.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.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
andunnegate
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.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
returnsFalse
.
Objects
- picos.glyphs.CAN_FACTOR_OUT_NEGATION¶
Operator glyphs for which negation may be factored out.
- Default value
(<picos.glyphs.Br object at 0x7f919adaaef0>, <picos.glyphs.Fn object at 0x7f919adaa860>, <picos.glyphs.Fn object at 0x7f919adaa410>, <picos.glyphs.Fn object at 0x7f919adaa5f0>, <picos.glyphs.Fn object at 0x7f919adaa3b0>, <picos.glyphs.Fn object...
- picos.glyphs.abs¶
Absolute value glyph.
- Default value
<picos.glyphs.Br object at 0x7f919adaae30>
- picos.glyphs.add¶
Addition glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9a80>
- picos.glyphs.affpart¶
Affine part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa110>
- picos.glyphs.and_¶
Logical and glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab0d0>
- picos.glyphs.bcasted¶
Broadcasted glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9e10>
- picos.glyphs.blinpart¶
Bilinear part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa050>
- picos.glyphs.closure¶
Set closure glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adab490>
- picos.glyphs.comma¶
Seperated by comma glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab610>
- picos.glyphs.compose¶
Function composition glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab550>
- picos.glyphs.compsep¶
Compact seperator glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab670>
- picos.glyphs.conj¶
Complex conugate glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa1d0>
- picos.glyphs.cstpart¶
Constant part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9f90>
- picos.glyphs.cubed¶
Cubed value glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada8a90>
- picos.glyphs.desvec¶
Symmetric de-vectorization glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa470>
- picos.glyphs.det¶
Determinant glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa2f0>
- picos.glyphs.diag¶
Diagonal matrix glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa3b0>
- picos.glyphs.div¶
Division glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada98a0>
- picos.glyphs.dotp¶
Scalar product glyph.
- Default value
<picos.glyphs.Br object at 0x7f919adaae90>
- picos.glyphs.element¶
Set element glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada8430>
- picos.glyphs.eq¶
Equality glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada8760>
- picos.glyphs.exp¶
Exponentiation glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa6b0>
- picos.glyphs.exparg¶
Expected value glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9ae0>
- picos.glyphs.expected¶
Epected value glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9c90>
- picos.glyphs.forall¶
Universal quantification glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab190>
- picos.glyphs.fromto¶
Range glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab3d0>
- picos.glyphs.frozen¶
Frozen mutables glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9f30>
- picos.glyphs.ge¶
Greater or equal glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada8640>
- picos.glyphs.gt¶
Greater than glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada8550>
- picos.glyphs.hadamard¶
Hadamard product glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada99c0>
- picos.glyphs.horicat¶
Horizontal concatenation glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada8220>
- picos.glyphs.htransp¶
Matrix hermitian transposition glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada8130>
- picos.glyphs.idmatrix¶
Identity matrix glyph.
- Default value
<picos.glyphs.Am object at 0x7f919adaafb0>
- picos.glyphs.imag¶
Imaginary part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa230>
- picos.glyphs.index¶
Index glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada81f0>
- picos.glyphs.infty¶
Infinity glyph.
- Default value
<picos.glyphs.Am object at 0x7f919adab010>
- picos.glyphs.interval¶
Interval glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab430>
- picos.glyphs.intrange¶
Integer range glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab2e0>
- picos.glyphs.inverse¶
Matrix inverse glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada8880>
- picos.glyphs.kron¶
Kronecker product glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9960>
- picos.glyphs.lambda_¶
Lambda symbol glyph.
- Default value
<picos.glyphs.Am object at 0x7f919adaaf50>
- picos.glyphs.le¶
Lesser or equal glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada9150>
- picos.glyphs.leadsto¶
Successorship glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab130>
- picos.glyphs.linpart¶
Linear part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa0b0>
- picos.glyphs.log¶
Logarithm glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa650>
- picos.glyphs.lt¶
Lesser than glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada8670>
- picos.glyphs.maindiag¶
Main diagonal glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa350>
- picos.glyphs.matrix¶
Matrix glyph.
- Default value
<picos.glyphs.Br object at 0x7f919adaaef0>
- picos.glyphs.max¶
Maximum glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa770>
- picos.glyphs.maxarg¶
The basic math operator glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada8460>
- picos.glyphs.min¶
Minimum glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa710>
- picos.glyphs.minarg¶
The basic math operator glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada86d0>
- picos.glyphs.mul¶
Multiplication glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9900>
- picos.glyphs.ncnorm¶
Nuclear Norm glyph.
- Default value
<picos.glyphs.Op object at 0x7f919adaa890>
- picos.glyphs.ncstpart¶
Nonconstant part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9ff0>
- picos.glyphs.neg¶
Negation glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9840>
- picos.glyphs.norm¶
Norm glyph.
- Default value
<picos.glyphs.Br object at 0x7f919adaadd0>
- picos.glyphs.or_¶
Logical or glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab070>
- picos.glyphs.parenth¶
Parenthesis glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab730>
- picos.glyphs.plsmns¶
Plus/Minus glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada97b0>
- picos.glyphs.pnorm¶
p-Norm glyph.
- Default value
<picos.glyphs.Op object at 0x7f919adaac80>
- picos.glyphs.power¶
Power glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada9750>
- picos.glyphs.pqnorm¶
pq-Norm glyph.
- Default value
<picos.glyphs.Op object at 0x7f919adaab30>
- picos.glyphs.probdist¶
Probability distribution glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9cf0>
- picos.glyphs.prod¶
Product glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa7d0>
- picos.glyphs.psdge¶
Lesser or equal w.r.t. the p.s.d. cone glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada84c0>
- picos.glyphs.psdle¶
Greater or equal w.r.t. the p.s.d. cone glyph.
- Default value
<picos.glyphs.Rl object at 0x7f919ada8490>
- picos.glyphs.ptrace¶
Matrix p-Trace glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9c30>
- picos.glyphs.ptrace_¶
Matrix partial trace glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9b40>
- picos.glyphs.ptransp¶
Matrix partial transposition glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada8190>
- picos.glyphs.ptransp_¶
Matrix partial transposition glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9ba0>
- picos.glyphs.quadpart¶
Quadratic part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa170>
- picos.glyphs.real¶
Real part glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa290>
- picos.glyphs.repr1¶
Representation glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab880>
- picos.glyphs.repr2¶
Long representation glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab790>
- picos.glyphs.reshaped¶
Column-major (Fortran) reshaped glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9ed0>
- picos.glyphs.reshaprm¶
Row-major (C-order) reshaped glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9e70>
- picos.glyphs.sep¶
Seperator glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab6d0>
- picos.glyphs.set¶
Set glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab4f0>
- picos.glyphs.shortint¶
Shortened interval glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab1f0>
- picos.glyphs.shuffled¶
Matrix reshuffling glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9d50>
- picos.glyphs.size¶
Matrix size/shape glyph.
- Default value
<picos.glyphs.Gl object at 0x7f919adab5b0>
- picos.glyphs.slice¶
Expression slicing glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9c00>
- picos.glyphs.spnorm¶
Spectral Norm glyph.
- Default value
<picos.glyphs.Op object at 0x7f919adaa9e0>
- picos.glyphs.sqrt¶
Square root glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919ada9db0>
- picos.glyphs.squared¶
Squared value glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada8c40>
- picos.glyphs.sub¶
Substraction glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada9a20>
- picos.glyphs.sum¶
Summation glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa860>
- picos.glyphs.svec¶
Symmetric vectorization glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa4d0>
- picos.glyphs.trace¶
Matrix trace glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa410>
- picos.glyphs.transp¶
Matrix transposition glyph.
- Default value
<picos.glyphs.Tr object at 0x7f919ada80d0>
- picos.glyphs.trilvec¶
Lower triangular vectorization glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa590>
- picos.glyphs.triuvec¶
Upper triangular vectorization glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa530>
- picos.glyphs.vec¶
Vectorization glyph.
- Default value
<picos.glyphs.Fn object at 0x7f919adaa5f0>
- picos.glyphs.vertcat¶
Vertical concatenation glyph.
- Default value
<picos.glyphs.Op object at 0x7f919ada83d0>