@@ -44,7 +44,61 @@ def S(name: str,
4444 is_cyclesymmetric : Optional [bool ] = None ,
4545 is_linear : Optional [bool ] = None ,
4646 custom_normalization : Optional [Transformer ] = None ) -> Expression :
47- """Shorthand notation for :func:`Expression.symbol`"""
47+ """
48+ Create new symbols from `names`. Symbols can have attributes,
49+ such as symmetries. If no attributes
50+ are specified and the symbol was previously defined, the attributes are inherited.
51+ Once attributes are defined on a symbol, they cannot be redefined later.
52+
53+ Examples
54+ --------
55+ Define a regular symbol and use it as a variable:
56+ >>> x = S('x')
57+ >>> e = x**2 + 5
58+ >>> print(e)
59+ x**2 + 5
60+
61+ Define a regular symbol and use it as a function:
62+ >>> f = S('f')
63+ >>> e = f(1,2)
64+ >>> print(e)
65+ f(1,2)
66+
67+
68+ Define a symmetric function:
69+ >>> f = S('f', is_symmetric=True)
70+ >>> e = f(2,1)
71+ >>> print(e)
72+ f(1,2)
73+
74+
75+ Define a linear and symmetric function:
76+ >>> p1, p2, p3, p4 = ES('p1', 'p2', 'p3', 'p4')
77+ >>> dot = S('dot', is_symmetric=True, is_linear=True)
78+ >>> e = dot(p2+2*p3,p1+3*p2-p3)
79+ dot(p1,p2)+2*dot(p1,p3)+3*dot(p2,p2)-dot(p2,p3)+6*dot(p2,p3)-2*dot(p3,p3)
80+
81+ Define a custom normalization function:
82+ >>> e = S('real_log', custom_normalization=Transformer().replace_all(E("x_(exp(x1_))"), E("x1_")))
83+ >>> E("real_log(exp(x)) + real_log(5)")
84+
85+ Parameters
86+ ----------
87+ name : str
88+ The name of the symbol
89+ is_symmetric : Optional[bool]
90+ Set to true if the symbol is symmetric.
91+ is_antisymmetric : Optional[bool]
92+ Set to true if the symbol is antisymmetric.
93+ is_cyclesymmetric : Optional[bool]
94+ Set to true if the symbol is cyclesymmetric.
95+ is_linear : Optional[bool]
96+ Set to true if the symbol is linear.
97+ custom_normalization : Optional[Transformer]
98+ A transformer that is called after every normalization. Note that the symbol
99+ name cannot be used in the transformer as this will lead to a definition of the
100+ symbol. Use a wildcard with the same attributes instead.
101+ """
48102
49103
50104@overload
@@ -54,15 +108,84 @@ def S(*names: str,
54108 is_cyclesymmetric : Optional [bool ] = None ,
55109 is_linear : Optional [bool ] = None ,
56110 custom_normalization : Optional [Transformer ] = None ) -> Sequence [Expression ]:
57- """Shorthand notation for :func:`Expression.symbol`"""
111+ """
112+ Create new symbols from `names`. Symbols can have attributes,
113+ such as symmetries. If no attributes
114+ are specified and the symbol was previously defined, the attributes are inherited.
115+ Once attributes are defined on a symbol, they cannot be redefined later.
116+
117+ Examples
118+ --------
119+ Define two regular symbols:
120+ >>> x, y = S('x', 'y')
121+
122+ Define two symmetric functions:
123+ >>> f, g = S('f', 'g', is_symmetric=True)
124+ >>> e = f(2,1)
125+ >>> print(e)
126+ f(1,2)
127+
128+ Parameters
129+ ----------
130+ name : str
131+ The name of the symbol
132+ is_symmetric : Optional[bool]
133+ Set to true if the symbol is symmetric.
134+ is_antisymmetric : Optional[bool]
135+ Set to true if the symbol is antisymmetric.
136+ is_cyclesymmetric : Optional[bool]
137+ Set to true if the symbol is cyclesymmetric.
138+ is_linear : Optional[bool]
139+ Set to true if the symbol is multilinear.
140+ custom_normalization : Optional[Transformer]
141+ A transformer that is called after every normalization. Note that the symbol
142+ name cannot be used in the transformer as this will lead to a definition of the
143+ symbol. Use a wildcard with the same attributes instead.
144+ """
58145
59146
60147def N (num : int | float | str | Decimal , relative_error : Optional [float ] = None ) -> Expression :
61- """Shorthand notation for :func:`Expression.num`"""
148+ """Create a new Symbolica number from an int, a float, or a string.
149+ A floating point number is kept as a float with the same precision as the input,
150+ but it can also be converted to the smallest rational number given a `relative_error`.
151+
152+ Examples
153+ --------
154+ >>> e = N(1) / 2
155+ >>> print(e)
156+ 1/2
157+
158+ >>> print(N(1/3))
159+ >>> print(N(0.33, 0.1))
160+ >>> print(N('0.333`3'))
161+ >>> print(N(Decimal('0.1234')))
162+ 3.3333333333333331e-1
163+ 1/3
164+ 3.33e-1
165+ 1.2340e-1
166+ """
62167
63168
64169def E (input : str ) -> Expression :
65- """Shorthand notation for :func:`Expression.parse`"""
170+ """
171+ Parse a Symbolica expression from a string.
172+
173+ Parameters
174+ ----------
175+ input: str
176+ An input string. UTF-8 character are allowed.
177+
178+ Examples
179+ --------
180+ >>> e = E('x^2+y+y*4')
181+ >>> print(e)
182+ x^2+5*y
183+
184+ Raises
185+ ------
186+ ValueError
187+ If the input is not a valid Symbolica expression.
188+ """
66189
67190
68191class AtomType (Enum ):
@@ -150,14 +273,9 @@ class Expression:
150273 is_linear : Optional [bool ] = None ,
151274 custom_normalization : Optional [Transformer ] = None ) -> Expression :
152275 """
153- Create a new symbol from a `name`. Symbols carry information about their attributes.
154- The symbol can signal that it is symmetric if it is used as a function
155- using `is_symmetric=True`, antisymmetric using `is_antisymmetric=True`,
156- cyclesymmetric using `is_cyclesymmetric=True`, and
157- multilinear using `is_linear=True`. If no attributes
158- are specified, the attributes are inherited from the symbol if it was already defined,
159- otherwise all attributes are set to `false`.
160-
276+ Create new symbols from `names`. Symbols can have attributes,
277+ such as symmetries. If no attributes
278+ are specified and the symbol was previously defined, the attributes are inherited.
161279 Once attributes are defined on a symbol, they cannot be redefined later.
162280
163281 Examples
@@ -187,6 +305,27 @@ class Expression:
187305 >>> dot = Expression.symbol('dot', is_symmetric=True, is_linear=True)
188306 >>> e = dot(p2+2*p3,p1+3*p2-p3)
189307 dot(p1,p2)+2*dot(p1,p3)+3*dot(p2,p2)-dot(p2,p3)+6*dot(p2,p3)-2*dot(p3,p3)
308+
309+ Define a custom normalization function:
310+ >>> e = S('real_log', custom_normalization=Transformer().replace_all(E("x_(exp(x1_))"), E("x1_")))
311+ >>> E("real_log(exp(x)) + real_log(5)")
312+
313+ Parameters
314+ ----------
315+ name : str
316+ The name of the symbol
317+ is_symmetric : Optional[bool]
318+ Set to true if the symbol is symmetric.
319+ is_antisymmetric : Optional[bool]
320+ Set to true if the symbol is antisymmetric.
321+ is_cyclesymmetric : Optional[bool]
322+ Set to true if the symbol is cyclesymmetric.
323+ is_linear : Optional[bool]
324+ Set to true if the symbol is linear.
325+ custom_normalization : Optional[Transformer]
326+ A transformer that is called after every normalization. Note that the symbol
327+ name cannot be used in the transformer as this will lead to a definition of the
328+ symbol. Use a wildcard with the same attributes instead.
190329 """
191330
192331 @overload
@@ -199,48 +338,38 @@ class Expression:
199338 is_linear : Optional [bool ] = None ,
200339 custom_normalization : Optional [Transformer ] = None ) -> Sequence [Expression ]:
201340 """
202- Create new symbols from `names`. Symbols carry information about their attributes.
203- The symbol can signal that it is symmetric if it is used as a function
204- using `is_symmetric=True`, antisymmetric using `is_antisymmetric=True`,
205- cyclesymmetric using `is_cyclesymmetric=True`, and
206- multilinear using `is_linear=True`. If no attributes
207- are specified, the attributes are inherited from the symbol if it was already defined,
208- otherwise all attributes are set to `false`. A transformer that is executed
209- after normalization can be defined with `custom_normalization`.
210-
341+ Create new symbols from `names`. Symbols can have attributes,
342+ such as symmetries. If no attributes
343+ are specified and the symbol was previously defined, the attributes are inherited.
211344 Once attributes are defined on a symbol, they cannot be redefined later.
212345
213346 Examples
214347 --------
215- Define a regular symbol and use it as a variable:
216- >>> x = Expression.symbol('x')
217- >>> e = x**2 + 5
218- >>> print(e)
219- x**2 + 5
220-
221- Define a regular symbol and use it as a function:
222- >>> f = Expression.symbol('f')
223- >>> e = f(1,2)
224- >>> print(e)
225- f(1,2)
226-
348+ Define two regular symbols:
349+ >>> x, y = Expression.symbol('x', 'y')
227350
228- Define a symmetric function :
229- >>> f = Expression.symbol('f', is_symmetric=True)
351+ Define two symmetric functions :
352+ >>> f, g = Expression.symbol('f', 'g ', is_symmetric=True)
230353 >>> e = f(2,1)
231354 >>> print(e)
232355 f(1,2)
233356
234-
235- Define a linear and symmetric function:
236- >>> p1, p2, p3, p4 = Expression.symbol('p1', 'p2', 'p3', 'p4')
237- >>> dot = Expression.symbol('dot', is_symmetric=True, is_linear=True)
238- >>> e = dot(p2+2*p3,p1+3*p2-p3)
239- dot(p1,p2)+2*dot(p1,p3)+3*dot(p2,p2)-dot(p2,p3)+6*dot(p2,p3)-2*dot(p3,p3)
240-
241- Define a custom normalization function:
242- >>> e = S('real_log', custom_normalization=Transformer().replace_all(E("x_(exp(x1_))"), E("x1_")))
243- >>> E("real_log(exp(x)) + real_log(5)")
357+ Parameters
358+ ----------
359+ name : str
360+ The name of the symbol
361+ is_symmetric : Optional[bool]
362+ Set to true if the symbol is symmetric.
363+ is_antisymmetric : Optional[bool]
364+ Set to true if the symbol is antisymmetric.
365+ is_cyclesymmetric : Optional[bool]
366+ Set to true if the symbol is cyclesymmetric.
367+ is_linear : Optional[bool]
368+ Set to true if the symbol is multilinear.
369+ custom_normalization : Optional[Transformer]
370+ A transformer that is called after every normalization. Note that the symbol
371+ name cannot be used in the transformer as this will lead to a definition of the
372+ symbol. Use a wildcard with the same attributes instead.
244373 """
245374
246375 @overload
0 commit comments