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.
BackslashOperator
¶ Bases:
object
Implements Matlab-style backslash operator for solving systems:
A \ b
The preparser converts this to multiplications using
BackslashOperator()
.EXAMPLES:
sage: preparse("A \\ matrix(QQ,2,1,[1/3,'2/3'])") "A * BackslashOperator() * matrix(QQ,Integer(2),Integer(1),[Integer(1)/Integer(3),'2/3'])" sage: preparse("A \\ matrix(QQ,2,1,[1/3,2*3])") 'A * BackslashOperator() * matrix(QQ,Integer(2),Integer(1),[Integer(1)/Integer(3),Integer(2)*Integer(3)])' sage: preparse("A \\ B + C") 'A * BackslashOperator() * B + C' sage: preparse("A \\ eval('C+D')") "A * BackslashOperator() * eval('C+D')" sage: preparse("A \\ x / 5") 'A * BackslashOperator() * x / Integer(5)' sage: preparse("A^3 \\ b") 'A**Integer(3) * BackslashOperator() * b'
-
class
sage.misc.misc.
GlobalCputime
(t)¶ Bases:
object
Container for CPU times of subprocesses.
AUTHOR:
Martin Albrecht - (2008-12): initial version
EXAMPLES:
Objects of this type are returned if
subprocesses=True
is passed tocputime()
: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
-
sage.misc.misc.
compose
(f, g)¶ Return the composition of one-variable functions: \(f \circ g\)
See also
nest()
- INPUT:
\(f\) – a function of one variable
\(g\) – another function of one variable
- OUTPUT:
A function, such that compose(f,g)(x) = f(g(x))
EXAMPLES:
sage: def g(x): return 3*x sage: def f(x): return x + 1 sage: h1 = compose(f,g) sage: h2 = compose(g,f) sage: _ = var ('x') sage: h1(x) 3*x + 1 sage: h2(x) 3*x + 3
sage: _ = function('f g') sage: _ = var ('x') sage: compose(f,g)(x) f(g(x))
-
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 sincet
. This is how much time Sage has spent using the CPU. Ifsubprocesses=False
this does not count time spent in subprocesses spawned by Sage (e.g., Gap, Singular, etc.). Ifsubprocesses=True
this function tries to take all subprocesses with a workingcputime()
implementation into account.The measurement for the main Sage process is done via a call to
resource.getrusage()
, so it avoids the wraparound problems intime.clock()
on Cygwin.INPUT:
t
- (optional) time in CPU seconds, ift
is a result from an earlier call withsubprocesses=True
, thensubprocesses=True
is assumed.subprocesses – (optional), include subprocesses (default:
False
)
OUTPUT:
float
- time in CPU seconds ifsubprocesses=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.
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.
exactly_one_is_true
(iterable)¶ Return whether exactly one element of
iterable
evaluatesTrue
.INPUT:
iterable
– an iterable object
OUTPUT:
A boolean.
Note
The implementation is suggested by stackoverflow entry.
EXAMPLES:
sage: from sage.misc.misc import exactly_one_is_true sage: exactly_one_is_true([]) False sage: exactly_one_is_true([True]) True sage: exactly_one_is_true([False]) False sage: exactly_one_is_true([True, True]) False sage: exactly_one_is_true([False, True]) True sage: exactly_one_is_true([True, False, True]) False sage: exactly_one_is_true([False, True, False]) True
-
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 Sobject
- 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 Sobject
- 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.
get_main_globals
()¶ Return the main global namespace.
EXAMPLES:
sage: from sage.misc.misc import get_main_globals sage: G = get_main_globals() sage: bla = 1 sage: G['bla'] 1 sage: bla = 2 sage: G['bla'] 2 sage: G['ble'] = 5 sage: ble 5
This is analogous to
globals()
, except that it can be called from any function, even if it is in a Python module:sage: def f(): ....: G = get_main_globals() ....: assert G['bli'] == 14 ....: G['blo'] = 42 sage: bli = 14 sage: f() sage: blo 42
ALGORITHM:
The main global namespace is discovered by going up the frame stack until the frame for the
__main__
module is found. Should this frame not be found (this should not occur in normal operation), an exception “ValueError: call stack is not deep enough” will be raised by_getframe
.See
inject_variable_test()
for a real test that this works within deeply nested calls in a function defined in a Python module.
-
sage.misc.misc.
inject_variable
(name, value, warn=True)¶ Inject a variable into the main global namespace.
INPUT:
name
– a stringvalue
– anythingwarn
– a boolean (default:False
)
EXAMPLES:
sage: from sage.misc.misc import inject_variable sage: inject_variable("a", 314) sage: a 314
A warning is issued the first time an existing value is overwritten:
sage: inject_variable("a", 271) doctest:...: RuntimeWarning: redefining global value `a` sage: a 271 sage: inject_variable("a", 272) sage: a 272
That’s because warn seem to not reissue twice the same warning:
sage: from warnings import warn sage: warn(“blah”) doctest:…: UserWarning: blah sage: warn(“blah”)
Warnings can be disabled:
sage: b = 3 sage: inject_variable("b", 42, warn=False) sage: b 42
Use with care!
-
sage.misc.misc.
inject_variable_test
(name, value, depth)¶ A function for testing deep calls to inject_variable
EXAMPLES:
sage: from sage.misc.misc import inject_variable_test sage: inject_variable_test("a0", 314, 0) sage: a0 314 sage: inject_variable_test("a1", 314, 1) sage: a1 314 sage: inject_variable_test("a2", 314, 2) sage: a2 314 sage: inject_variable_test("a2", 271, 2) doctest:...: RuntimeWarning: redefining global value `a2` sage: a2 271
-
sage.misc.misc.
is_in_string
(line, pos)¶ Return
True
if the character at positionpos
inline
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
-
sage.misc.misc.
is_iterator
(it)¶ Tests if it is an iterator.
The mantra
if hasattr(it, 'next')
was used to tests ifit
is an iterator. This is not quite correct sinceit
could have anext
methods with a different semantic.EXAMPLES:
sage: it = iter([1,2,3]) sage: is_iterator(it) True sage: class wrong(): # py2 ....: def __init__(self): self.n = 5 ....: def next(self): ....: self.n -= 1 ....: if self.n == 0: raise StopIteration ....: return self.n sage: class wrong(): # py3 ....: def __init__(self): self.n = 5 ....: def __next__(self): ....: self.n -= 1 ....: if self.n == 0: raise StopIteration ....: return self.n sage: x = wrong() sage: is_iterator(x) False sage: list(x) # py2 Traceback (most recent call last): ... TypeError: iteration over non-sequence sage: list(x) # py3 Traceback (most recent call last): ... TypeError: 'wrong' object is not iterable sage: class good(wrong): ....: def __iter__(self): return self sage: x = good() sage: is_iterator(x) True sage: list(x) [4, 3, 2, 1] sage: P = Partitions(3) sage: is_iterator(P) False sage: is_iterator(iter(P)) True
-
sage.misc.misc.
is_sublist
(X, Y)¶ Test whether
X
is a sublist ofY
.EXAMPLES:
sage: from sage.misc.misc import is_sublist sage: S = [1, 7, 3, 4, 18] sage: is_sublist([1, 7], S) True sage: is_sublist([1, 3, 4], S) True sage: is_sublist([1, 4, 3], S) False sage: is_sublist(S, S) True
-
sage.misc.misc.
nest
(f, n, x)¶ Return \(f(f(...f(x)...))\), where the composition occurs n times.
See also
compose()
andself_compose()
- INPUT:
\(f\) – a function of one variable
\(n\) – a nonnegative integer
\(x\) – any input for \(f\)
- OUTPUT:
\(f(f(...f(x)...))\), where the composition occurs n times
EXAMPLES:
sage: def f(x): return x^2 + 1 sage: x = var('x') sage: nest(f, 3, x) ((x^2 + 1)^2 + 1)^2 + 1
sage: _ = function('f') sage: _ = var('x') sage: nest(f, 10, x) f(f(f(f(f(f(f(f(f(f(x))))))))))
sage: _ = function('f') sage: _ = var('x') sage: nest(f, 0, x) x
-
sage.misc.misc.
newton_method_sizes
(N)¶ Return 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: L = [] sage: for x in powerset(ZZ): ....: if i > 10: ....: break ....: else: ....: i += 1 ....: L.append(x) sage: print(" ".join(str(x) for x in L)) [] [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]) <generator object ...powerset at 0x...> 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.
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
- lists
- floating point number between 0 and 1
OUTPUT: list
EXAMPLES:
sage: from sage.misc.misc import is_sublist sage: S = [1,7,3,4,18] sage: sublist = random_sublist(S, 0.5); sublist # random [1, 3, 4] sage: is_sublist(sublist, S) True sage: sublist = random_sublist(S, 0.5); sublist # random [1, 3] sage: is_sublist(sublist, S) True
-
sage.misc.misc.
sage_makedirs
(dirname, mode=511)¶ Python version of
mkdir -p
: try to create a directory, and also create all intermediate directories as necessary. Succeed silently if the directory already exists (unlikeos.makedirs()
). Raise other errors (like permission errors) normally.EXAMPLES:
sage: from sage.misc.misc import sage_makedirs sage: sage_makedirs(DOT_SAGE) # no output
The following fails because we are trying to create a directory in place of an ordinary file:
sage: filename = tmp_filename() sage: sage_makedirs(filename) Traceback (most recent call last): ... OSError: [Errno ...] File exists: ...
-
sage.misc.misc.
some_tuples
(elements, repeat, bound, max_samples=None)¶ Return an iterator over at most
bound
number ofrepeat
-tuples ofelements
.INPUT:
elements
– an iterablerepeat
– integer (defaultNone
), the length of the tuples to be returned. IfNone
, just returns entries fromelements
.bound
– the maximum number of tuples returned (ignored ifmax_samples
given)max_samples
– non-negative integer (defaultNone
). If given, then a sample of the possible tuples will be returned, instead of the first few in the standard order.
OUTPUT:
If
max_samples
is not provided, an iterator over the firstbound
tuples of lengthrepeat
, in the standard nested-for-loop order.If
max_samples
is provided, a list of at mostmax_samples
tuples, sampled uniformly from the possibilities. In this case,elements
must be finite.
-
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: L = [] sage: for x in powerset(ZZ): ....: if i > 10: ....: break ....: else: ....: i += 1 ....: L.append(x) sage: print(" ".join(str(x) for x in L)) [] [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]) <generator object ...powerset at 0x...> 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.
try_read
(obj, splitlines=False)¶ Determine if a given object is a readable file-like object and if so read and return its contents.
That is, the object has a callable method named
read()
which takes no arguments (exceptself
) then the method is executed and the contents are returned.Alternatively, if the
splitlines=True
is given, firstsplitlines()
is tried, then if that failsread().splitlines()
.If either method fails,
None
is returned.INPUT:
obj
– typically a \(file\) or \(io.BaseIO\) object, but any other object with aread()
method is accepted.splitlines
– \(bool\), optional; if True, return a list of lines instead of a string.
EXAMPLES:
sage: import io sage: filename = tmp_filename() sage: from sage.misc.misc import try_read sage: with open(filename, 'w') as fobj: ....: _ = fobj.write('a\nb\nc') sage: with open(filename) as fobj: ....: print(try_read(fobj)) a b c sage: with open(filename) as fobj: ....: try_read(fobj, splitlines=True) ['a\n', 'b\n', 'c']
The following example is identical to the above example on Python 3, but different on Python 2 where
open != io.open
:sage: with io.open(filename) as fobj: ....: print(try_read(fobj)) a b c
I/O buffers:
sage: buf = io.StringIO(u'a\nb\nc') sage: print(try_read(buf)) a b c sage: _ = buf.seek(0); try_read(buf, splitlines=True) [u'a\n', u'b\n', u'c'] sage: buf = io.BytesIO(b'a\nb\nc') sage: try_read(buf) == b'a\nb\nc' True sage: _ = buf.seek(0) sage: try_read(buf, splitlines=True) == [b'a\n', b'b\n', b'c'] True
Custom readable:
sage: class MyFile(object): ....: def read(self): return 'Hello world!' sage: try_read(MyFile()) 'Hello world!' sage: try_read(MyFile(), splitlines=True) ['Hello world!']
Not readable:
sage: try_read(1) is None True
-
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
- iterabley
- 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: uniq([1, 1, 8, -5, 3, -5, -13, 13, -13]) doctest:...: DeprecationWarning: the output of uniq(X) being sorted is deprecated; use sorted(set(X)) instead if you want sorted output See https://trac.sagemath.org/27014 for details. [-13, -5, 1, 3, 8, 13]
-
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)¶