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¶
A math atom glyph. |
|
A math operator glyph with enclosing brackets. |
|
A math operator glyph in function form. |
|
The basic “glyph”, an (algebraic) string formatting template. |
|
A string created from a |
|
The basic math operator glyph. |
|
A string created from a math operator glyph. |
|
A math relation glyph. |
|
A math glyph in superscript/trailer form. |
Functions¶
Let PICOS create future strings using only ASCII characters. |
|
Describe the addition of two values in a clever way. |
|
Describe the division of one value by another in a clever way. |
|
Describe an inner product in a clever way. |
|
Describe the multiplocation of two values in a clever way. |
|
Describe the negation of a value in a clever way. |
|
Describe the substraction of a value from another in a clever way. |
|
Describe a column vector with the given symbolic entries. |
|
Let PICOS create future strings using only unicode characters. |
|
Return a variable name not present in the given string. |
|
Whether the given string was created by the given glyph. |
|
Check if a value can be unnegated by |
|
Let PICOS create future strings using only ISO 8859-1 characters. |
|
Create an ad-hoc composite function glyphs. |
|
Describe matrix concatenation in a clever way. |
|
Update glyphs that are based upon other glyphs. |
|
Describe a row vector with the given symbolic entries. |
|
Format a scalar value. |
|
Describe a matrix shape that can contain wildcards. |
|
Show output from all glyphs. |
|
Let PICOS create future strings using only unicode characters. |
|
Unnegate a value, usually a glyph-created string, in a sensible way. |
Data¶
Classes¶
Am¶
Br¶
Fn¶
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.
-
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 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.
-
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.
-
OpStr¶
-
class
picos.glyphs.
OpStr
(string, glyph, operands)[source]¶ Bases:
picos.glyphs.GlStr
A string created from a math operator glyph.
Rl¶
Functions¶
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 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]'
clever_div¶
clever_dotp¶
clever_mul¶
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 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]'
col_vectorize¶
default¶
-
picos.glyphs.
default
(rebuildDerivedGlyphs=True)¶ Let PICOS create future strings using only unicode characters.
free_var_name¶
from_glyph¶
latin1¶
make_function¶
matrix_cat¶
-
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]'
row_vectorize¶
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
andunnegate
unnecessarily.Example
>>> from picos.glyphs import scalar >>> str(1.0) '1.0' >>> scalar(1.0) '1'
shape¶
show¶
unicode¶
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
returnsFalse
.
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.
blinpart
¶ Bilinear part 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.
desvec
¶ Symmetric de-vectorization 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.
exparg
¶ Expected value glyph.
-
picos.glyphs.
expected
¶ Epected value glyph.
-
picos.glyphs.
forall
¶ Universal quantification glyph.
-
picos.glyphs.
fromto
¶ Range glyph.
-
picos.glyphs.
frozen
¶ Frozen mutables 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.
index
¶ Index glyph.
-
picos.glyphs.
infty
¶ Infinity glyph.
-
picos.glyphs.
interval
¶ Interval glyph.
-
picos.glyphs.
intrange
¶ Integer range glyph.
-
picos.glyphs.
inverse
¶ Matrix inverse 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.
maxarg
¶ The basic math operator glyph.
-
picos.glyphs.
min
¶ Minimum glyph.
-
picos.glyphs.
minarg
¶ The basic math operator glyph.
-
picos.glyphs.
mul
¶ Multiplication glyph.
-
picos.glyphs.
ncnorm
¶ Nuclear Norm glyph.
-
picos.glyphs.
ncstpart
¶ Nonconstant part 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.
probdist
¶ Probability distribution glyph.
-
picos.glyphs.
prod
¶ Product 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.
shuffled
¶ Matrix reshuffling 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.
svec
¶ Symmetric vectorization 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.
vec
¶ Vectorization glyph.
-
picos.glyphs.
vertcat
¶ Vertical concatenation glyph.