2.1.1 misc.misc - Miscellaneous functions

The module misc.misc defines the following methods:

add( x, [z=0])

Return the sum of the elements of x. If x is empty, return z.

INPUT:
    x -- iterable
    z -- the "0" that will be returned if x is empty.
    
OUTPUT:
    object

A very straightforward usage:
    sage: add([1,2,3])
    6

In the following example, xrange is an iterator:

sage: add(xrange(101))
5050

Append two sequences.

sage: add([[1,1], [-1,0]])
[1, 1, -1, 0]

The zero can be anything:

sage: add([], "zero")
'zero'

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.

cputime( [t=0])

Return the time in CPU second since SAGE started, or with optional argument t, return the time since time t.

INPUT:
    t -- (optional) float, time in CPU seconds
OUTPUT:
    float -- time in CPU seconds

sage: t = cputime()
sage: F = factor(2**389-1)
sage: print cputime(t)
2.83

NOTE: There is also a time command that one can also use from the SAGE shell, e.g.,

sage: time F = factor(2**389-1)
CPU times: user 2.80 s, sys: 0.03 s, total: 2.83 s
Wall time: 2.92

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.

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

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 some 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)

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.

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

lambda functions are very useful when using the forall function. As a toy example we test whether certain integers are >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 <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)

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.

sage: get_verbose()
0
sage: set_verbose(2)
sage: get_verbose()
2
sage: set_verbose(0)

get_verbose_files( )

mul( x, [z=None])

Return the product of the elements in the list x. If optimal argument z is not given, start the product with the first element of the list, otherwise use z. The empty product is the int 1 if z is not specified, and is z if given.

sage: mul([1,2,34])
68
sage: mul([2,3], 5)
30

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

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

Note: 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.

prod( x, [z=None])

Return the product of the elements in the list x. If optimal argument z is not given, start the product with the first element of the list, otherwise use z. The empty product is the int 1 if z is not specified, and is z if given.

sage: mul([1,2,34])
68
sage: mul([2,3], 5)
30

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

sage: S = [1,7,3,4,18]
sage: random_sublist(S, 0.5)
[7]
sage: random_sublist(S, 0.5)
[1, 7, 3]

set_verbose( level, [files=[]])

Set the global SAGE verbosity level.

INPUT:
    int level: an integer between 0 and 2, inclusive.
    files: list of files to make verbose (include "all")
           in the list to make ALL sage files verbose.
OUTPUT:
    changes the state of the verbosity flag and
    possibly appends to the list of files that are verbose.

sage: set_verbose(2)
sage: _ = verbose("This is SAGE.", level=1)
VERBOSE1 (?): This is SAGE.
sage: _ = verbose("This is SAGE.", level=2)
VERBOSE2 (?): This is SAGE.
sage: _ = verbose("This is SAGE.", level=3)
[no output]

set_verbose_files( file_name)

sourcefile( object)
Work out which source or compiled file an object was defined in.

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

sage: union([1,2,3,4], [5,6])
[1, 3, 2, 5, 4, 6]
sage: union([1,2,3,4,5,6], [5,6])
[1, 3, 2, 5, 4, 6]
sage: union((1,2,3,4,5,6), [5,6])
[1, 3, 2, 5, 4, 6]
sage: union((1,2,3,4,5,6), set([5,6]))
[1, 3, 2, 5, 4, 6]

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.

sage: uniq([1,1,8,-5,3,-5,'a','x','a'])
[-5, 1, 3, 8, 'a', 'x']

unset_verbose_files( file_name)

verbose( [mesg=None], [t=1], [level=0], [caller_name=])

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()

sage: set_verbose(1)
sage: t = cputime()
sage: t = verbose("This is SAGE.", t, level=1, caller_name="william")
VERBOSE1 (william): This is SAGE. (time = 0.0)

version( )

Return the version of SAGE.

INPUT:
   nothing
OUTPUT:
   str

sage: print version()
SAGE Version x.y.z, Export Date: xxxx-xx-xx-xxxx
Distributed under the terms of the GNU General Public License (GPL)

See About this document... for information on suggesting changes.