class_docstr: Singularity functions are a class of discontinuous functions.
  
  Explanation
  ===========
  
  Singularity functions take a variable, an offset, and an exponent as
  arguments. These functions are represented using Macaulay brackets as:
  
  SingularityFunction(x, a, n) := <x - a>^n
  
  The singularity function will automatically evaluate to
  ``Derivative(DiracDelta(x - a), x, -n - 1)`` if ``n < 0``
  and ``(x - a)**n*Heaviside(x - a, 1)`` if ``n >= 0``.
  
  Examples
  ========
  
  >>> from sympy import SingularityFunction, diff, Piecewise, DiracDelta, Heaviside, Symbol
  >>> from sympy.abc import x, a, n
  >>> SingularityFunction(x, a, n)
  SingularityFunction(x, a, n)
  >>> y = Symbol('y', positive=True)
  >>> n = Symbol('n', nonnegative=True)
  >>> SingularityFunction(y, -10, n)
  (y + 10)**n
  >>> y = Symbol('y', negative=True)
  >>> SingularityFunction(y, 10, n)
  0
  >>> SingularityFunction(x, 4, -1).subs(x, 4)
  oo
  >>> SingularityFunction(x, 10, -2).subs(x, 10)
  oo
  >>> SingularityFunction(4, 1, 5)
  243
  >>> diff(SingularityFunction(x, 1, 5) + SingularityFunction(x, 1, 4), x)
  4*SingularityFunction(x, 1, 3) + 5*SingularityFunction(x, 1, 4)
  >>> diff(SingularityFunction(x, 4, 0), x, 2)
  SingularityFunction(x, 4, -2)
  >>> SingularityFunction(x, 4, 5).rewrite(Piecewise)
  Piecewise(((x - 4)**5, x >= 4), (0, True))
  >>> expr = SingularityFunction(x, a, n)
  >>> y = Symbol('y', positive=True)
  >>> n = Symbol('n', nonnegative=True)
  >>> expr.subs({x: y, a: -10, n: n})
  (y + 10)**n
  
  The methods ``rewrite(DiracDelta)``, ``rewrite(Heaviside)``, and
  ``rewrite('HeavisideDiracDelta')`` returns the same output. One can use any
  of these methods according to their choice.
  
  >>> expr = SingularityFunction(x, 4, 5) + SingularityFunction(x, -3, -1) - SingularityFunction(x, 0, -2)
  >>> expr.rewrite(Heaviside)
  (x - 4)**5*Heaviside(x - 4, 1) + DiracDelta(x + 3) - DiracDelta(x, 1)
  >>> expr.rewrite(DiracDelta)
  (x - 4)**5*Heaviside(x - 4, 1) + DiracDelta(x + 3) - DiracDelta(x, 1)
  >>> expr.rewrite('HeavisideDiracDelta')
  (x - 4)**5*Heaviside(x - 4, 1) + DiracDelta(x + 3) - DiracDelta(x, 1)
  
  See Also
  ========
  
  DiracDelta, Heaviside
  
  References
  ==========
  
  .. [1] https://en.wikipedia.org/wiki/Singularity_function
class_docstr_tok: ["Singularity","functions","are","a","class","of","discontinuous","functions",".","Explanation","===========","Singularity","functions","take","a","variable",",","an","offset",",","and","an","exponent","as","arguments",".","These","functions","are","represented","using","Macaulay","brackets","as",":","SingularityFunction","(","x",",","a",",","n",")",":","=","<","x","-","a",">","^n","The","singularity","function","will","automatically","evaluate","to","``","Derivative","(","DiracDelta","(","x","-","a",")",",","x",",","-n","-","1",")","``","if","``","n","<","0","``","and","``","(","x","-","a",")","*","*","n","*","Heaviside","(","x","-","a",",","1",")","``","if","``","n",">","=","0","``",".","Examples","========",">",">",">","from","sympy","import","SingularityFunction",",","diff",",","Piecewise",",","DiracDelta",",","Heaviside",",","Symbol",">",">",">","from","sympy.abc","import","x",",","a",",","n",">",">",">","SingularityFunction","(","x",",","a",",","n",")","SingularityFunction","(","x",",","a",",","n",")",">",">",">","y","=","Symbol","(","'","y","'",",","positive=True",")",">",">",">","n","=","Symbol","(","'n","'",",","nonnegative=True",")",">",">",">","SingularityFunction","(","y",",","-10",",","n",")","(","y","+","10",")","*","*","n",">",">",">","y","=","Symbol","(","'","y","'",",","negative=True",")",">",">",">","SingularityFunction","(","y",",","10",",","n",")","0",">",">",">","SingularityFunction","(","x",",","4",",","-1",")",".subs","(","x",",","4",")","oo",">",">",">","SingularityFunction","(","x",",","10",",","-2",")",".subs","(","x",",","10",")","oo",">",">",">","SingularityFunction","(","4",",","1",",","5",")","243",">",">",">","diff","(","SingularityFunction","(","x",",","1",",","5",")","+","SingularityFunction","(","x",",","1",",","4",")",",","x",")","4","*","SingularityFunction","(","x",",","1",",","3",")","+","5","*","SingularityFunction","(","x",",","1",",","4",")",">",">",">","diff","(","SingularityFunction","(","x",",","4",",","0",")",",","x",",","2",")","SingularityFunction","(","x",",","4",",","-2",")",">",">",">","SingularityFunction","(","x",",","4",",","5",")",".rewrite","(","Piecewise",")","Piecewise","(","(","(","x","-","4",")","*","*","5",",","x",">","=","4",")",",","(","0",",","True",")",")",">",">",">","expr","=","SingularityFunction","(","x",",","a",",","n",")",">",">",">","y","=","Symbol","(","'","y","'",",","positive=True",")",">",">",">","n","=","Symbol","(","'n","'",",","nonnegative=True",")",">",">",">","expr.subs","(","{","x",":","y",",","a",":","-10",",","n",":","n","}",")","(","y","+","10",")","*","*","n","The","methods","``","rewrite","(","DiracDelta",")","``",",","``","rewrite","(","Heaviside",")","``",",","and","``","rewrite","(","'HeavisideDiracDelta","'",")","``","returns","the","same","output",".","One","can","use","any","of","these","methods","according","to","their","choice",".",">",">",">","expr","=","SingularityFunction","(","x",",","4",",","5",")","+","SingularityFunction","(","x",",","-3",",","-1",")","-","SingularityFunction","(","x",",","0",",","-2",")",">",">",">","expr.rewrite","(","Heaviside",")","(","x","-","4",")","*","*","5","*","Heaviside","(","x","-","4",",","1",")","+","DiracDelta","(","x","+","3",")","-","DiracDelta","(","x",",","1",")",">",">",">","expr.rewrite","(","DiracDelta",")","(","x","-","4",")","*","*","5","*","Heaviside","(","x","-","4",",","1",")","+","DiracDelta","(","x","+","3",")","-","DiracDelta","(","x",",","1",")",">",">",">","expr.rewrite","(","'HeavisideDiracDelta","'",")","(","x","-","4",")","*","*","5","*","Heaviside","(","x","-","4",",","1",")","+","DiracDelta","(","x","+","3",")","-","DiracDelta","(","x",",","1",")","See","Also","========","DiracDelta",",","Heaviside","References","==========","..","[","1","]","https",":","\/\/en.wikipedia.org\/wiki\/Singularity_function"]
docstr: Returns a simplified form or a value of Singularity Function depending
  on the argument passed by the object.
  
  Explanation
  ===========
  
  The ``eval()`` method is automatically called when the
  ``SingularityFunction`` class is about to be instantiated and it
  returns either some simplified instance or the unevaluated instance
  depending on the argument passed. In other words, ``eval()`` method is
  not needed to be called explicitly, it is being called and evaluated
  once the object is called.
  
  Examples
  ========
  
  >>> from sympy import SingularityFunction, Symbol, nan
  >>> from sympy.abc import x, a, n
  >>> SingularityFunction(x, a, n)
  SingularityFunction(x, a, n)
  >>> SingularityFunction(5, 3, 2)
  4
  >>> SingularityFunction(x, a, nan)
  nan
  >>> SingularityFunction(x, 3, 0).subs(x, 3)
  1
  >>> SingularityFunction(4, 1, 5)
  243
  >>> x = Symbol('x', positive = True)
  >>> a = Symbol('a', negative = True)
  >>> n = Symbol('n', nonnegative = True)
  >>> SingularityFunction(x, a, n)
  (-a + x)**n
  >>> x = Symbol('x', negative = True)
  >>> a = Symbol('a', positive = True)
  >>> SingularityFunction(x, a, n)
  0
docstr_tok: ["Returns","a","simplified","form","or","a","value","of","Singularity","Function","depending","on","the","argument","passed","by","the","object",".","Explanation","===========","The","``","eval","(",")","``","method","is","automatically","called","when","the","``","SingularityFunction","``","class","is","about","to","be","instantiated","and","it","returns","either","some","simplified","instance","or","the","unevaluated","instance","depending","on","the","argument","passed",".","In","other","words",",","``","eval","(",")","``","method","is","not","needed","to","be","called","explicitly",",","it","is","being","called","and","evaluated","once","the","object","is","called",".","Examples","========",">",">",">","from","sympy","import","SingularityFunction",",","Symbol",",","nan",">",">",">","from","sympy.abc","import","x",",","a",",","n",">",">",">","SingularityFunction","(","x",",","a",",","n",")","SingularityFunction","(","x",",","a",",","n",")",">",">",">","SingularityFunction","(","5",",","3",",","2",")","4",">",">",">","SingularityFunction","(","x",",","a",",","nan",")","nan",">",">",">","SingularityFunction","(","x",",","3",",","0",")",".subs","(","x",",","3",")","1",">",">",">","SingularityFunction","(","4",",","1",",","5",")","243",">",">",">","x","=","Symbol","(","'","x","'",",","positive","=","True",")",">",">",">","a","=","Symbol","(","'","a","'",",","negative","=","True",")",">",">",">","n","=","Symbol","(","'n","'",",","nonnegative","=","True",")",">",">",">","SingularityFunction","(","x",",","a",",","n",")","(","-a","+","x",")","*","*","n",">",">",">","x","=","Symbol","(","'","x","'",",","negative","=","True",")",">",">",">","a","=","Symbol","(","'","a","'",",","positive","=","True",")",">",">",">","SingularityFunction","(","x",",","a",",","n",")","0"]
code: def eval(cls, variable, offset, exponent):
      """
      Returns a simplified form or a value of Singularity Function depending
      on the argument passed by the object.
  
      Explanation
      ===========
  
      The ``eval()`` method is automatically called when the
      ``SingularityFunction`` class is about to be instantiated and it
      returns either some simplified instance or the unevaluated instance
      depending on the argument passed. In other words, ``eval()`` method is
      not needed to be called explicitly, it is being called and evaluated
      once the object is called.
  
      Examples
      ========
  
      >>> from sympy import SingularityFunction, Symbol, nan
      >>> from sympy.abc import x, a, n
      >>> SingularityFunction(x, a, n)
      SingularityFunction(x, a, n)
      >>> SingularityFunction(5, 3, 2)
      4
      >>> SingularityFunction(x, a, nan)
      nan
      >>> SingularityFunction(x, 3, 0).subs(x, 3)
      1
      >>> SingularityFunction(4, 1, 5)
      243
      >>> x = Symbol('x', positive = True)
      >>> a = Symbol('a', negative = True)
      >>> n = Symbol('n', nonnegative = True)
      >>> SingularityFunction(x, a, n)
      (-a + x)**n
      >>> x = Symbol('x', negative = True)
      >>> a = Symbol('a', positive = True)
      >>> SingularityFunction(x, a, n)
      0
  
      """
  
      x = variable
      a = offset
      n = exponent
      shift = x - a
  
      if fuzzy_not(im(shift).is_zero):
          raise ValueError(
              "Singularity Functions are defined only for Real Numbers."
          )
      if fuzzy_not(im(n).is_zero):
          raise ValueError(
              "Singularity Functions are not defined for imaginary exponents."
          )
      if shift is S.NaN or n is S.NaN:
          return S.NaN
      if (n + 2).is_negative:
          raise ValueError(
              "Singularity Functions are not defined for exponents less than -2."
          )
      if shift.is_extended_negative:
          return S.Zero
      if n.is_nonnegative:
          if (
              shift.is_zero
          ):  # use literal 0 in case of Symbol('z', zero=True)
              return S.Zero**n
          if shift.is_extended_nonnegative:
              return shift**n
      if n in (S.NegativeOne, -2):
          if shift.is_negative or shift.is_extended_positive:
              return S.Zero
          if shift.is_zero:
              return oo
  
file_path: sympy/sympy/functions/special/singularity_functions.py
imports: from sympy.core import S, oo, diff
  from sympy.core.function import Function, ArgumentIndexError
  from sympy.core.logic import fuzzy_not
  from sympy.core.relational import Eq
  from sympy.functions.elementary.complexes import im
  from sympy.functions.elementary.piecewise import Piecewise
  from sympy.functions.special.delta_functions import Heaviside
label_desc: Use image node_id 2 for calling the SingularityFunction obj's underlying member method code with example usage: obj.eval(cls, variable, offset, exponent) and returns: S, S, unknown, unknown, S, oo