Miscellaneous functions

AUTHORS:

  • William Stein
  • William Stein (2006-04-26): added workaround for Windows where most users’ home directory has a space in it.
  • Robert Bradshaw (2007-09-20): Ellipsis range/iterator.
class sage.misc.misc.AttrCallObject(name, args, kwds)
__call__(x)

Gets the self.name method from x, calls it with self.args and self.kwds, and returns the result.

EXAMPLES:

sage: f = attrcall('core', 3)
sage: f(Partition([4,2]))
[4, 2]
__init__(name, args, kwds)

TESTS:

sage: f = attrcall('core', 3)
sage: loads(dumps(f))
*.core(3)
__repr__()

Returns a string representation of this object. The star in the output represents the object passed into self.

EXAMPLES:

sage: attrcall('core', 3)
*.core(3)
sage: attrcall('hooks', flatten=True)
*.hooks(flatten=True)
sage: attrcall('hooks', 3, flatten=True)
*.hooks(3, flatten=True)
__weakref__
list of weak references to the object (if defined)
class sage.misc.misc.CopiedClass

A simple class to test nested_pickle.

EXAMPLES:

sage: from sage.misc.misc import *
sage: loads(dumps(CopiedClass.NestedClass()))
<sage.misc.misc.MainClass.NestedClass object at 0x...>
sage: loads(dumps(CopiedClass.NestedSubClass()))
<sage.misc.misc.MainClass.NestedClass.NestedSubClass object at 0x...>
sage: loads(dumps(SubClass()))
<sage.misc.misc.SubClass object at 0x...>
NestedClass
alias of MainClass.NestedClass
NestedSubClass
alias of MainClass.NestedClass.NestedSubClass
class SubClass

A simple class to test nested_pickle.

EXAMPLES:

sage: from sage.misc.misc import *
sage: loads(dumps(SubClass.NestedClass()))
<sage.misc.misc.MainClass.NestedClass object at 0x...>
CopiedClass.__weakref__
list of weak references to the object (if defined)
class sage.misc.misc.GlobalCputime(t)

Container for CPU times of subprocesses.

AUTHOR:

  • Martin Albrecht - (2008-12): initial version

EXAMPLE:

Objects of this type are returned if subprocesses=True is passed to cputime():

sage: cputime(subprocesses=True) # indirect doctest, output random
0.2347431

We can use it to keep track of the CPU time spent in Singular for example:

sage: t = cputime(subprocesses=True)
sage: P = PolynomialRing(QQ,7,'x')
sage: I = sage.rings.ideal.Katsura(P)
sage: gb = I.groebner_basis() # calls Singular
sage: cputime(subprocesses=True) - t # output random
0.462987

For further processing we can then convert this container to a float:

sage: t = cputime(subprocesses=True)
sage: float(t) #output somewhat random
2.1088339999999999

See also

cputime()

__add__(other)

EXAMPLE:

sage: t = cputime(subprocesses=True)
sage: P = PolynomialRing(QQ,7,'x')
sage: I = sage.rings.ideal.Katsura(P)
sage: gb = I.groebner_basis() # calls Singular
sage: cputime(subprocesses=True) + t # output random
2.798708
__float__()

EXAMPLE:

sage: t = cputime(subprocesses=True)
sage: float(t) #output somewhat random
2.1088339999999999
__init__(t)

Create a new CPU time object which also keeps track of subprocesses.

EXAMPLE:

sage: from sage.misc.misc import GlobalCputime
sage: ct = GlobalCputime(0.0); ct
0.0...
__repr__()

EXAMPLE:

sage: cputime(subprocesses=True) # indirect doctest, output random
0.2347431
__sub__(other)

EXAMPLE:

sage: t = cputime(subprocesses=True)
sage: P = PolynomialRing(QQ,7,'x')
sage: I = sage.rings.ideal.Katsura(P)
sage: gb = I.groebner_basis() # calls Singular
sage: cputime(subprocesses=True) - t # output random
0.462987
class sage.misc.misc.MainClass

A simple class to test nested_pickle.

EXAMPLES:

sage: from sage.misc.misc import *
sage: loads(dumps(MainClass()))
<sage.misc.misc.MainClass object at 0x...>
NestedClass
alias of MainClass.NestedClass
__metaclass__
alias of NestedClassMetaclass
__weakref__
list of weak references to the object (if defined)
class sage.misc.misc.NestedClassMetaclass(*args)

A metaclass for nested pickling.

Check that one can use a metaclass to ensure nested_pickle is called on any derived subclass:

sage: from sage.misc.misc import NestedClassMetaclass
sage: class ASuperClass(object):
...       __metaclass__ = NestedClassMetaclass
...
sage: class A3(ASuperClass):
...       class B(object):
...           pass
...
sage: A3.B.__name__
'A3.B'
sage: getattr(sys.modules['__main__'], 'A3.B', 'Not found')
<class '__main__.A3.B'>
__init__(*args)

This invokes the nested_pickle on construction.

sage: from sage.misc.misc import NestedClassMetaclass sage: class A(object): ... __metaclass__ = NestedClassMetaclass ... class B(object): ... pass ... sage: A.B <class ‘__main__.A.B’> sage: getattr(sys.modules[‘__main__’], ‘A.B’, ‘Not found’) <class ‘__main__.A.B’>

class sage.misc.misc.SubClass

A simple class to test nested_pickle.

EXAMPLES:

sage: from sage.misc.misc import *
sage: loads(dumps(SubClass.NestedClass()))
<sage.misc.misc.MainClass.NestedClass object at 0x...>
sage.misc.misc.__mysig(a, b)
sage.misc.misc._xsrange(a, b=None, step=1)
sage.misc.misc.alarm(seconds)

Raise a KeyboardInterrupt exception in a given number of seconds. This is useful for automatically interrupting long computations and can be trapped using exception handling (just catch KeyboardInterrupt).

INPUT:

  • seconds - integer

TESTS:

sage: try: alarm(1); sleep(2)
... except KeyboardInterrupt: print "Alarm went off"
Alarm went off
sage.misc.misc.assert_attribute(x, attr, init=None)
If the object x has the attribute attr, do nothing. If not, set x.attr to init.
sage.misc.misc.attrcall(name, *args, **kwds)

Returns a callable which takes in an object, gets the method named name from that object, and calls it with the specified arguments and keywords.

INPUT:

  • name - a string of the name of the method you want to call
  • args, kwds - arguments and keywords to be passed to the method

EXAMPLES:

sage: f = attrcall('core', 3); f
*.core(3)
sage: [f(p) for p in Partitions(5)]
[[2], [1, 1], [1, 1], [3, 1, 1], [2], [2], [1, 1]]
sage.misc.misc.branch_current_hg()
Return the current hg Mercurial branch name. If the branch is ‘main’, which is the default branch, then just ” is returned.
sage.misc.misc.branch_current_hg_notice(branch)

Return a string describing the current branch and that the library is being loaded. This is called by the SAGE_ROOT/local/bin/sage-sage script.

INPUT:

  • string - a representation of the name of the Sage library branch.

OUTPUT: string

Note

If the branch is main, then return an empty string.

class sage.misc.misc.cached_attribute(method, name=None)

Computes attribute value and caches it in the instance.

__get__(inst, cls)
__init__(method, name=None)
__weakref__
list of weak references to the object (if defined)
class sage.misc.misc.cached_class_attribute(method, name=None)

Computes attribute value and caches it in the class.

__get__(inst, cls)
sage.misc.misc.cancel_alarm()
sage.misc.misc.cmp_props(left, right, props)
sage.misc.misc.coeff_repr(c, is_latex=False)
sage.misc.misc.cputime(t=0, subprocesses=False)

Return the time in CPU seconds since Sage started, or with optional argument t, return the time since t. This is how much time Sage has spent using the CPU. If subprocesses=False this does not count time spent in subprocesses spawned by Sage (e.g., Gap, Singular, etc.). If subprocesses=True this function tries to take all subprocesses with a working cputime() implementation into account.

The measurement for the main Sage process is done via a call to resource.getrusage(), so it avoids the wraparound problems in time.clock() on Cygwin.

INPUT:

  • t - (optional) time in CPU seconds, if t is a result from an earlier call with subprocesses=True, then subprocesses=True is assumed.
  • subprocesses – (optional), include subprocesses (default: False)

OUTPUT:

  • float - time in CPU seconds if subprocesses=False
  • GlobalCputime - object which holds CPU times of subprocesses otherwise

EXAMPLES:

sage: t = cputime()
sage: F = gp.factor(2^199-1)
sage: cputime(t)          # somewhat random
0.010999000000000092

sage: t = cputime(subprocesses=True)
sage: F = gp.factor(2^199-1)
sage: cputime(t) # somewhat random
0.091999

sage: w = walltime()
sage: F = gp.factor(2^199-1)
sage: walltime(w)         # somewhat random
0.58425593376159668

Note

Even with subprocesses=True there is no guarantee that the CPU time is reported correctly because subprocesses can be started and terminated at any given time.

sage.misc.misc.delete_tmpfiles()
sage.misc.misc.deprecation(message)

Issue a deprecation warning.

EXAMPLE:

sage: def foo():
...    sage.misc.misc.deprecation("The function foo is replaced by bar.")
...
sage: def my_function():
...    foo()
...
sage: my_function() # random: I don't know how to test the output.
doctest:1: DeprecationWarning: The function foo is replaced by bar.
sage.misc.misc.ellipsis_iter(*args, **kwds)

Same as ellipsis_range, but as an iterator (and may end with an Ellipsis).

See also ellipsis_range.

Use (1,2,...) notation.

EXAMPLES:

sage: A = ellipsis_iter(1,2,Ellipsis)
sage: [A.next() for _ in range(10)]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
sage: A.next()
11
sage: A = ellipsis_iter(1,3,5,Ellipsis)
sage: [A.next() for _ in range(10)]
[1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
sage: A = ellipsis_iter(1,2,Ellipsis,5,10,Ellipsis)
sage: [A.next() for _ in range(10)]
[1, 2, 3, 4, 5, 10, 11, 12, 13, 14]

TESTS:

These were carefully chosen tests, only to be changed if the semantics of ellipsis ranges change. In other words, if they don’t pass it’s probably a bug in the implementation, not in the doctest.

sage: list(1,..,10)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
sage: list(1,3,..,10)
[1, 3, 5, 7, 9]
sage: list(1,..,10,..,20)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
sage: list(1,3,..,10,..,20)
[1, 3, 5, 7, 9, 10, 12, 14, 16, 18, 20]
sage: list(1,3,..,10,10,..,20)
[1, 3, 5, 7, 9, 10, 12, 14, 16, 18, 20]
sage: list(0,2,..,10,10,..,20,20,..,25)
[0, 2, 4, 6, 8, 10, 10, 12, 14, 16, 18, 20, 20, 22, 24]
sage: list(10,..,1)
[]
sage: list(10,11,..,1)
[]
sage: list(10,9,..,1)
[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
sage: list(100,..,10,..,20)
[10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
sage: list(0,..,10,..,-20)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
sage: list(100,..,10,..,-20)
[]
sage: list(100,102,..,10,..,20)
[10, 12, 14, 16, 18, 20]
sage.misc.misc.ellipsis_range(*args, **kwds)

Return arithmetic sequence determined by the numeric arguments and ellipsis. Best illustrated by examples.

Use [1,2,..,n] notation.

EXAMPLES:

sage: ellipsis_range(1,Ellipsis,11,100)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 100]
sage: ellipsis_range(0,2,Ellipsis,10,Ellipsis,20)
[0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
sage: ellipsis_range(0,2,Ellipsis,11,Ellipsis,20)
[0, 2, 4, 6, 8, 10, 11, 13, 15, 17, 19]
sage: ellipsis_range(0,2,Ellipsis,11,Ellipsis,20, step=3)
[0, 2, 5, 8, 11, 14, 17, 20]
sage: ellipsis_range(10,Ellipsis,0)
[]

TESTS: These were carefully chosen tests, only to be changed if the semantics of ellipsis ranges change. In other words, if they don’t pass it’s probably a bug in the implementation, not in the doctest.

Note 10 only appears once (though it is in both ranges).

sage: ellipsis_range(0,Ellipsis,10,Ellipsis,20,step=2)
[0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

Sometimes one or more ranges is empty.

sage: ellipsis_range(100,Ellipsis,10,Ellipsis,20,step=2)
[10, 12, 14, 16, 18, 20]
sage: ellipsis_range(0,Ellipsis,10,Ellipsis,-20,step=2)
[0, 2, 4, 6, 8, 10]
sage: ellipsis_range(100,Ellipsis,10,Ellipsis,-20,step=2)
[]

We always start on the leftmost point of the range.

sage: ellipsis_range(0,Ellipsis,10,Ellipsis,20,step=3)
[0, 3, 6, 9, 10, 13, 16, 19]
sage: ellipsis_range(100,Ellipsis,10,Ellipsis,20,step=3)
[10, 13, 16, 19]
sage: ellipsis_range(0,Ellipsis,10,Ellipsis,-20,step=3)
[0, 3, 6, 9]
sage: ellipsis_range(100,Ellipsis,10,Ellipsis,-20,step=3)
[]
sage: ellipsis_range(0,1,Ellipsis,-10)
[]
sage: ellipsis_range(0,1,Ellipsis,-10,step=1)
[0]
sage: ellipsis_range(100,0,1,Ellipsis,-10)
[100]

Note the duplicate 5 in the output.

sage: ellipsis_range(0,Ellipsis,5,5,Ellipsis,10)
[0, 1, 2, 3, 4, 5, 5, 6, 7, 8, 9, 10]

Examples in which the step determines the parent of the elements:

sage: [1..3, step=0.5]
[1.00000000000000, 1.50000000000000, 2.00000000000000, 2.50000000000000, 3.00000000000000]
sage: v = [1..5, step=1/1]; v
[1, 2, 3, 4, 5]
sage: parent(v[2])
Rational Field
sage.misc.misc.embedded()

Return True if this copy of Sage is running embedded in the Sage notebook.

EXAMPLES:

sage: sage.misc.misc.embedded()    # output True if in the notebook
False
sage.misc.misc.exists(S, P)

If S contains an element x such that P(x) is True, this function returns True and the element x. Otherwise it returns False and None.

Note that this function is NOT suitable to be used in an if-statement or in any place where a boolean expression is expected. For those situations, use the Python built-in

any(P(x) for x in S)

INPUT:

  • S - object (that supports enumeration)
  • P - function that returns True or False

OUTPUT:

  • bool - whether or not P is True for some element x of S
  • object - x

EXAMPLES: lambda functions are very useful when using the exists function:

sage: exists([1,2,5], lambda x : x > 7)
(False, None)
sage: exists([1,2,5], lambda x : x > 3)
(True, 5)

The following example is similar to one in the MAGMA handbook. We check whether certain integers are a sum of two (small) cubes:

sage: cubes = [t**3 for t in range(-10,11)]
sage: exists([(x,y) for x in cubes for y in cubes], lambda v : v[0]+v[1] == 218)
(True, (-125, 343))
sage: exists([(x,y) for x in cubes for y in cubes], lambda v : v[0]+v[1] == 219)
(False, None)
sage.misc.misc.forall(S, P)

If P(x) is true every x in S, return True and None. If there is some element x in S such that P is not True, return False and x.

Note that this function is NOT suitable to be used in an if-statement or in any place where a boolean expression is expected. For those situations, use the Python built-in

all(P(x) for x in S)

INPUT:

  • S - object (that supports enumeration)
  • P - function that returns True or False

OUTPUT:

  • bool - whether or not P is True for all elements of S
  • object - x

EXAMPLES: lambda functions are very useful when using the forall function. As a toy example we test whether certain integers are greater than 3.

sage: forall([1,2,5], lambda x : x > 3)
(False, 1)
sage: forall([1,2,5], lambda x : x > 0)
(True, None)

Next we ask whether every positive integer less than 100 is a product of at most 2 prime factors:

sage: forall(range(1,100),  lambda n : len(factor(n)) <= 2)
(False, 30)

The answer is no, and 30 is a counterexample. However, every positive integer 100 is a product of at most 3 primes.

sage: forall(range(1,100),  lambda n : len(factor(n)) <= 3)
(True, None)
sage.misc.misc.generic_cmp(x, y)

Compare x and y and return -1, 0, or 1.

This is similar to x.__cmp__(y), but works even in some cases when a .__cmp__ method isn’t defined.

sage.misc.misc.get_verbose()

Return the global Sage verbosity level.

INPUT: int level: an integer between 0 and 2, inclusive.

OUTPUT: changes the state of the verbosity flag.

EXAMPLES:

sage: get_verbose()
0
sage: set_verbose(2)
sage: get_verbose()
2
sage: set_verbose(0)
sage.misc.misc.get_verbose_files()
sage.misc.misc.getitem(v, n)

Variant of getitem that coerces to an int if a TypeError is raised.

(This is not needed anymore - classes should define an __index__ method.)

Thus, e.g., getitem(v,n) will work even if v is a Python list and n is a Sage integer.

EXAMPLES:

sage: v = [1,2,3]

The following used to fail in Sage <= 1.3.7. Now it works fine:

sage: v[ZZ(1)]          
2

This always worked.

sage: getitem(v, ZZ(1))
2
sage.misc.misc.graphics_filename(ext='png')
Return the next available canonical filename for a plot/graphics file.
sage.misc.misc.is_in_string(line, pos)

Returns True if the character at position pos in line occurs within a string.

EXAMPLES:

sage: from sage.misc.misc import is_in_string
sage: line = 'test(\'#\')'
sage: is_in_string(line, line.rfind('#'))
True
sage: is_in_string(line, line.rfind(')'))
False
class sage.misc.misc.lazy_prop(calculate_function)
__call__(obj, _=None)
__init__(calculate_function)
__weakref__
list of weak references to the object (if defined)
sage.misc.misc.modify_for_nested_pickle(cls, name_prefix, module)

Modify the subclasses of the given class to be picklable, by giving them a mangled name and putting the mangled name in the module namespace.

INPUTS:

  • cls - The class to modify.
  • name_prefix - The prefix to prepend to the class name.
  • module - The module object to modify with the mangled name.

EXAMPLES:

sage: from sage.misc.misc import *
sage: class A(object):
...       class B(object):
...           pass
...
sage: module = sys.modules['__main__']
sage: A.B.__name__
'B'
sage: getattr(module, 'A.B', 'Not found')
'Not found'
sage: modify_for_nested_pickle(A, 'A', sys.modules['__main__'])
sage: A.B.__name__
'A.B'
sage: getattr(module, 'A.B', 'Not found')
<class '__main__.A.B'>
sage.misc.misc.nested_pickle(cls)

This decorator takes a class that potentially contains nested classes. For each such nested class, its name is modified to a new illegal identifier, and that name is set in the module. For example, if you have:

sage: from sage.misc.misc import nested_pickle
sage: module = sys.modules['__main__']
sage: class A(object):
...       class B:
...           pass
sage: nested_pickle(A)
<class '__main__.A'>

then the name of class B will be modified to ‘A.B’, and the ‘A.B’ attribute of the module will be set to class B:

sage: A.B.__name__
'A.B'
sage: getattr(module, 'A.B', 'Not found')
<class __main__.A.B at ...>

In Python 2.6, decorators work with classes; then @nested_pickle should work as a decorator:

sage: @nested_pickle    # todo: not implemented
...   class A2(object):
...       class B:
...           pass
sage: A2.B.__name__    # todo: not implemented
'A2.B'
sage: getattr(module, 'A2.B', 'Not found')    # todo: not implemented
<class __main__.A2.B at ...>

EXAMPLES:

sage: from sage.misc.misc import *
sage: loads(dumps(MainClass.NestedClass())) # indirect doctest
<sage.misc.misc.MainClass.NestedClass object at 0x...>
sage.misc.misc.newton_method_sizes(N)

Returns a sequence of integers 1 = a_1 \leq a_2 \leq \cdots \leq a_n = N such that a_j = \lceil a_{j+1} / 2 \rceil for all j.

This is useful for Newton-style algorithms that double the precision at each stage. For example if you start at precision 1 and want an answer to precision 17, then it’s better to use the intermediate stages 1, 2, 3, 5, 9, 17 than to use 1, 2, 4, 8, 16, 17.

INPUT:

  • N - positive integer

EXAMPLES:

sage: newton_method_sizes(17)
[1, 2, 3, 5, 9, 17]
sage: newton_method_sizes(16)
[1, 2, 4, 8, 16]
sage: newton_method_sizes(1)
[1]

AUTHORS:

  • David Harvey (2006-09-09)
sage.misc.misc.pad_zeros(s, size=3)

EXAMPLES:

sage: pad_zeros(100)
'100'
sage: pad_zeros(10)
'010'
sage: pad_zeros(10, 5)
'00010'
sage: pad_zeros(389, 5)
'00389'
sage: pad_zeros(389, 10)
'0000000389'
sage.misc.misc.powerset(X)

Iterator over the list of all subsets of the iterable X, in no particular order. Each list appears exactly once, up to order.

INPUT:

  • X - an iterable

OUTPUT: iterator of lists

EXAMPLES:

sage: list(powerset([1,2,3]))
[[], [1], [2], [1, 2], [3], [1, 3], [2, 3], [1, 2, 3]]
sage: [z for z in powerset([0,[1,2]])]
[[], [0], [[1, 2]], [0, [1, 2]]]

Iterating over the power set of an infinite set is also allowed:

sage: i = 0
sage: for x in powerset(ZZ):
...    if i > 10:
...       break
...    else:
...       i += 1
...    print x,
[] [0] [1] [0, 1] [-1] [0, -1] [1, -1] [0, 1, -1] [2] [0, 2] [1, 2]

You may also use subsets as an alias for powerset:

sage: subsets([1,2,3])   # random object location in output
<generator object at 0xaeae418c>
sage: list(subsets([1,2,3]))
[[], [1], [2], [1, 2], [3], [1, 3], [2, 3], [1, 2, 3]]

The reason we return lists instead of sets is that the elements of
sets must be hashable and many structures on which one wants the
powerset consist of non-hashable objects.

AUTHORS:

  • William Stein
  • Nils Bruin (2006-12-19): rewrite to work for not-necessarily finite objects X.
sage.misc.misc.prop(f)
sage.misc.misc.random_sublist(X, s)

Return a pseudo-random sublist of the list X where the probability of including a particular element is s.

INPUT:

  • X - list
  • s - floating point number between 0 and 1

OUTPUT: list

EXAMPLES:

sage: S = [1,7,3,4,18]
sage: random_sublist(S, 0.5)
[1, 3, 4]
sage: random_sublist(S, 0.5)
[1, 3]
sage.misc.misc.repr_lincomb(symbols, coeffs, is_latex=False)

Compute a string representation of a linear combination of some formal symbols.

INPUT:

  • symbols - list of symbols
  • coeffs - list of coefficients of the symbols

OUTPUT:

  • str - a string

EXAMPLES:

sage: repr_lincomb(['a','b','c'], [1,2,3])
'a + 2*b + 3*c'
sage: repr_lincomb(['a','b','c'], [1,'2+3*x',3])
'a + (2+3*x)*b + 3*c'
sage: repr_lincomb(['a','b','c'], ['1+x^2','2+3*x',3])
'(1+x^2)*a + (2+3*x)*b + 3*c'
sage: repr_lincomb(['a','b','c'], ['1+x^2','-2+3*x',3])
'(1+x^2)*a + (-2+3*x)*b + 3*c'
sage: repr_lincomb(['a','b','c'], [1,-2,-3])
'a - 2*b - 3*c'
sage: t = PolynomialRing(RationalField(),'t').gen()
sage: repr_lincomb(['a', 's', ''], [-t,t-2,t**2+2])
'-t*a + (t-2)*s + (t^2+2)'
sage.misc.misc.set_verbose(level, files='all')

Set the global Sage verbosity level.

INPUT:

  • level - an integer between 0 and 2, inclusive.

  • files (default: ‘all’): list of files to make verbose, or

    ‘all’ to make ALL files verbose (the default).

OUTPUT: changes the state of the verbosity flag and possibly appends to the list of files that are verbose.

EXAMPLES:

sage: set_verbose(2)
sage: verbose("This is Sage.", level=1)  # not tested
VERBOSE1 (?): This is Sage.
sage: verbose("This is Sage.", level=2)  # not tested
VERBOSE2 (?): This is Sage.
sage: verbose("This is Sage.", level=3)  # not tested
[no output]
sage: set_verbose(0)
sage.misc.misc.set_verbose_files(file_name)
sage.misc.misc.sourcefile(object)
Work out which source or compiled file an object was defined in.
sage.misc.misc.srange(start, end=None, step=1, universe=None, check=True, include_endpoint=False, endpoint_tolerance=1.0000000000000001e-05)

Return list of numbers a, a+step, ..., a+k*step, where a+k*step < b and a+(k+1)*step >= b over exact rings, and makes a best attempt for inexact rings (see note below).

This provides one way to iterate over Sage integers as opposed to Python int’s. It also allows you to specify step sizes for such an iteration. Note, however, that what is returned is a full list of Integers and not an iterator. It is potentially much slower than the Python range function, depending on the application. The function xsrange() provides an iterator with similar functionality which would usually be more efficient than using srange().

INPUT:

  • a - number
  • b - number (default: None)
  • step - number (default: 1)
  • universe - Parent or type where all the elements should live (default: deduce from inputs)
  • check - make sure a, b, and step all lie in the same universe
  • include_endpoint - whether or not to include the endpoint (default: False)
  • endpoint_tolerance - used to determine whether or not the endpoint is hit for inexact rings (default 1e-5)

OUTPUT:

  • list

If b is None, then b is set equal to a and a is set equal to the 0 in the parent of b.

Unlike range, a and b can be any type of numbers, and the resulting list involves numbers of that type.

Note

The list elements are computed via repeated addition rather than multiplication, which may produce slightly different results with inexact rings. For example:

sage: sum([1.1] * 10) == 1.1 * 10
False

Also, the question of whether the endpoint is hit exactly for a given a + k*step is fuzzy for an inexact ring. If a + k*step = b for some k within endpoint_tolerance of being integral, it is considered an exact hit, thus avoiding spurious values falling just below the endpoint.

Note

This function is called srange to distinguish it from the built-in Python range command. The s at the beginning of the name stands for “Sage”.

EXAMPLES:

sage: v = srange(5); v
[0, 1, 2, 3, 4]
sage: type(v[2])
<type 'sage.rings.integer.Integer'>
sage: srange(1, 10)
[1, 2, 3, 4, 5, 6, 7, 8, 9]
sage: srange(10, 1, -1)
[10, 9, 8, 7, 6, 5, 4, 3, 2]
sage: srange(10,1,-1, include_endpoint=True)
[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
sage: srange(1, 10, universe=RDF)
[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]

sage: srange(1, 10, 1/2)
[1, 3/2, 2, 5/2, 3, 7/2, 4, 9/2, 5, 11/2, 6, 13/2, 7, 15/2, 8, 17/2, 9, 19/2]    
sage: srange(1, 5, 0.5)
[1.00000000000000, 1.50000000000000, 2.00000000000000, 2.50000000000000, 3.00000000000000, 3.50000000000000, 4.00000000000000, 4.50000000000000]
sage: srange(0, 1, 0.4)
[0.000000000000000, 0.400000000000000, 0.800000000000000]
sage: srange(1.0, 5.0, include_endpoint=True)
[1.00000000000000, 2.00000000000000, 3.00000000000000, 4.00000000000000, 5.00000000000000]
sage: srange(1.0, 1.1)
[1.00000000000000]
sage: srange(1.0, 1.0)
[]
sage: V = VectorSpace(QQ, 2)
sage: srange(V([0,0]), V([5,5]), step=V([2,2]))
[(0, 0), (2, 2), (4, 4)]

Including the endpoint:

sage: srange(0, 10, step=2, include_endpoint=True)
[0, 2, 4, 6, 8, 10]
sage: srange(0, 10, step=3, include_endpoint=True)
[0, 3, 6, 9]

Try some inexact rings:

sage: srange(0.5, 1.1, 0.1, universe=RDF, include_endpoint=False)
[0.5, 0.6, 0.7, 0.8, 0.9, 1.0]
sage: srange(0.5, 1, 0.1, universe=RDF, include_endpoint=False)
[0.5, 0.6, 0.7, 0.8, 0.9]
sage: srange(0.5, 0.9, 0.1, universe=RDF, include_endpoint=False)
[0.5, 0.6, 0.7, 0.8]
sage: srange(0, 1.1, 0.1, universe=RDF, include_endpoint=True)
[0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1]
sage: srange(0, 0.2, 0.1, universe=RDF, include_endpoint=True)
[0.0, 0.1, 0.2]
sage: srange(0, 0.3, 0.1, universe=RDF, include_endpoint=True)
[0.0, 0.1, 0.2, 0.3]
sage.misc.misc.strunc(s, n=60)
Truncate at first space after position n, adding ‘...’ if nontrivial truncation.
sage.misc.misc.subsets(X)

Iterator over the list of all subsets of the iterable X, in no particular order. Each list appears exactly once, up to order.

INPUT:

  • X - an iterable

OUTPUT: iterator of lists

EXAMPLES:

sage: list(powerset([1,2,3]))
[[], [1], [2], [1, 2], [3], [1, 3], [2, 3], [1, 2, 3]]
sage: [z for z in powerset([0,[1,2]])]
[[], [0], [[1, 2]], [0, [1, 2]]]

Iterating over the power set of an infinite set is also allowed:

sage: i = 0
sage: for x in powerset(ZZ):
...    if i > 10:
...       break
...    else:
...       i += 1
...    print x,
[] [0] [1] [0, 1] [-1] [0, -1] [1, -1] [0, 1, -1] [2] [0, 2] [1, 2]

You may also use subsets as an alias for powerset:

sage: subsets([1,2,3])   # random object location in output
<generator object at 0xaeae418c>
sage: list(subsets([1,2,3]))
[[], [1], [2], [1, 2], [3], [1, 3], [2, 3], [1, 2, 3]]

The reason we return lists instead of sets is that the elements of
sets must be hashable and many structures on which one wants the
powerset consist of non-hashable objects.

AUTHORS:

  • William Stein
  • Nils Bruin (2006-12-19): rewrite to work for not-necessarily finite objects X.
sage.misc.misc.sxrange(start, end=None, step=1, universe=None, check=True, include_endpoint=False, endpoint_tolerance=1.0000000000000001e-05)

Return an iterator over numbers a, a+step, ...,  a+k*step, where a+k*step < b and a+(k+1)*step > b.

INPUT:
universe – Parent or type where all the elements should live (default: deduce from inputs) check – make sure a, b, and step all lie in the same universe include_endpoint – whether or not to include the endpoint (default: False) endpoint_tolerance – used to determine whether or not the endpoint is hit for inexact rings (default 1e-5)
  • a - number
  • b - number
  • step - number (default: 1)

OUTPUT: iterator

Unlike range, a and b can be any type of numbers, and the resulting iterator involves numbers of that type.

See also

srange()

Note

This function is called xsrange to distinguish it from the builtin Python xrange command.

EXAMPLES:

sage: list(xsrange(1,10))
[1, 2, 3, 4, 5, 6, 7, 8, 9]
sage: Q = RationalField()
sage: list(xsrange(1, 10, Q('1/2')))
[1, 3/2, 2, 5/2, 3, 7/2, 4, 9/2, 5, 11/2, 6, 13/2, 7, 15/2, 8, 17/2, 9, 19/2]    
sage: list(xsrange(1, 5, 0.5))
[1.00000000000000, 1.50000000000000, 2.00000000000000, 2.50000000000000, 3.00000000000000, 3.50000000000000, 4.00000000000000, 4.50000000000000]
sage: list(xsrange(0, 1, 0.4))
[0.000000000000000, 0.400000000000000, 0.800000000000000]

Negative ranges are also allowed:

sage: list(xrange(4,1,-1))
[4, 3, 2]
sage: list(sxrange(4,1,-1))
[4, 3, 2]
sage: list(sxrange(4,1,-1/2))
[4, 7/2, 3, 5/2, 2, 3/2]
sage.misc.misc.tmp_dir(name='dir')
Create and return a temporary directory in $HOME/.sage/temp/hostname/pid/
sage.misc.misc.tmp_filename(name='tmp')
sage.misc.misc.to_gmp_hex(n)
sage.misc.misc.todo(mesg='')
sage.misc.misc.typecheck(x, C, var='x')
Check that x is of instance C. If not raise a TypeError with an error message.
sage.misc.misc.union(x, y=None)

Return the union of x and y, as a list. The resulting list need not be sorted and can change from call to call.

INPUT:

  • x - iterable
  • y - iterable (may optionally omitted)

OUTPUT: list

EXAMPLES:

sage: answer = union([1,2,3,4], [5,6]); answer
[1, 2, 3, 4, 5, 6]
sage: union([1,2,3,4,5,6], [5,6]) == answer
True
sage: union((1,2,3,4,5,6), [5,6]) == answer
True
sage: union((1,2,3,4,5,6), set([5,6])) == answer
True
sage.misc.misc.uniq(x)

Return the sublist of all elements in the list x that is sorted and is such that the entries in the sublist are unique.

EXAMPLES:

sage: v = uniq([1,1,8,-5,3,-5,'a','x','a'])
sage: v            # potentially random ordering of output
['a', 'x', -5, 1, 3, 8]
sage: set(v) == set(['a', 'x', -5, 1, 3, 8])
True
sage.misc.misc.unset_verbose_files(file_name)
sage.misc.misc.verbose(mesg='', t=0, level=1, caller_name=None)

Print a message if the current verbosity is at least level.

INPUT:

  • mesg - str, a message to print
  • t - int, optional, if included, will also print cputime(t), - which is the time since time t. Thus t should have been obtained with t=cputime()
  • level - int, (default: 1) the verbosity level of what we are printing
  • caller_name - string (default: None), the name of the calling function; in most cases Python can deduce this, so it need not be provided.

OUTPUT: possibly prints a message to stdout; also returns cputime()

EXAMPLE:

sage: set_verbose(1)
sage: t = cputime()
sage: t = verbose("This is Sage.", t, level=1, caller_name="william")       # not tested
VERBOSE1 (william): This is Sage. (time = 0.0)
sage: set_verbose(0)
sage.misc.misc.walltime(t=0)

Return the wall time in second, or with optional argument t, return the wall time since time t. “Wall time” means the time on a wall clock, i.e., the actual time.

INPUT:

  • t - (optional) float, time in CPU seconds

OUTPUT:

  • float - time in seconds

EXAMPLES:

sage: w = walltime()
sage: F = factor(2^199-1)
sage: walltime(w)   # somewhat random
0.8823847770690918
sage.misc.misc.word_wrap(s, ncols=85)
sage.misc.misc.xsrange(start, end=None, step=1, universe=None, check=True, include_endpoint=False, endpoint_tolerance=1.0000000000000001e-05)

Return an iterator over numbers a, a+step, ...,  a+k*step, where a+k*step < b and a+(k+1)*step > b.

INPUT:
universe – Parent or type where all the elements should live (default: deduce from inputs) check – make sure a, b, and step all lie in the same universe include_endpoint – whether or not to include the endpoint (default: False) endpoint_tolerance – used to determine whether or not the endpoint is hit for inexact rings (default 1e-5)
  • a - number
  • b - number
  • step - number (default: 1)

OUTPUT: iterator

Unlike range, a and b can be any type of numbers, and the resulting iterator involves numbers of that type.

See also

srange()

Note

This function is called xsrange to distinguish it from the builtin Python xrange command.

EXAMPLES:

sage: list(xsrange(1,10))
[1, 2, 3, 4, 5, 6, 7, 8, 9]
sage: Q = RationalField()
sage: list(xsrange(1, 10, Q('1/2')))
[1, 3/2, 2, 5/2, 3, 7/2, 4, 9/2, 5, 11/2, 6, 13/2, 7, 15/2, 8, 17/2, 9, 19/2]    
sage: list(xsrange(1, 5, 0.5))
[1.00000000000000, 1.50000000000000, 2.00000000000000, 2.50000000000000, 3.00000000000000, 3.50000000000000, 4.00000000000000, 4.50000000000000]
sage: list(xsrange(0, 1, 0.4))
[0.000000000000000, 0.400000000000000, 0.800000000000000]

Negative ranges are also allowed:

sage: list(xrange(4,1,-1))
[4, 3, 2]
sage: list(sxrange(4,1,-1))
[4, 3, 2]
sage: list(sxrange(4,1,-1/2))
[4, 7/2, 3, 5/2, 2, 3/2]

Previous topic

Abstract methods

Next topic

Sage package management commands

This Page