This is Python.info, produced by Macaulay2, version 1.25.11

Python -- interface to Python
*****************************

Description
===========

This package provides a basic interface to run Python code within Macaulay2 and
to convert back and forth between Python and Macaulay2 objects.

+-----------------------------------------------------------------------------+
|i1 : toPython {1, 2/3, "foo", (1, 2, 3), hashTable {"foo" => "bar"}}         |
|                                                                             |
|o1 = [1, 0.6666666666666666, 'foo', (1, 2, 3), {'foo': 'bar'}]               |
|                                                                             |
|o1 : PythonObject of class list                                              |
+-----------------------------------------------------------------------------+
|i2 : value pythonValue "[1, 2/3, 'foo', (1, 2, 3), {'foo' : 'bar'}]"         |
|                                                                             |
|o2 = {1, .666667, foo, (1, 2, 3), HashTable{"foo" => bar}}                   |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : math = import "math"                                                    |
|                                                                             |
|o3 = <module 'math' from '/usr/lib64/python3.12/lib-dynload/math.cpython-312-|
|     x86_64-linux-gnu.so'>                                                   |
|                                                                             |
|o3 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+
|i4 : math@@sqrt 2                                                            |
|                                                                             |
|o4 = 1.4142135623730951                                                      |
|                                                                             |
|o4 : PythonObject of class float                                             |
+-----------------------------------------------------------------------------+

The loadPackage(...,Configuration=>...) (Macaulay2Doc),
option accepts an "executable" option to specify the path to the Python
executable, e.g., for working with virtual environments.  At least Python
version 3.8 is required for this feature to work.

tutorials

evaluating code

working with modules

classes

getting help

Authors
=======

  * Daniel R. Grayson (see https://faculty.math.illinois.edu/~dan/ )
    <danielrichardgrayson@gmail.com>
  * Doug Torrance (see https://webwork.piedmont.edu/~dtorrance )
    <dtorrance@piedmont.edu>

Version
=======

This documentation describes version 1.0 of Python, released November 8, 2025.

Citation
========

If you have used this package in your research, please cite it as follows:

+----------------------------------------------------------------------------+
|@misc{PythonSource,                                                         |
|  title = {{Python: interface to Python. Version~1.0}},                     |
|  author = {Daniel R. Grayson and Doug Torrance},                           |
|  howpublished = {A \emph{Macaulay2} package available at                   |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}}|
|}                                                                           |
|                                                                            |
+----------------------------------------------------------------------------+

Exports
=======

  * Types
      * PythonContext -- persistent Python execution
        environment
      * PythonObject -- a Python object
  * Functions and commands
      * addPyToM2Function -- convenience function for
        adding value hooks
      * import -- import a Python module
      * installNumPyMethods -- install NumPy
        methods
      * objectType -- type of a python object
      * pipInstall -- install a Python package
      * pythonHelp -- run Python's interactive help utility
      * pythonRunScript -- execute a sequence of Python
        statements
      * pythonValue -- execute Python source code from a
        string
      * runSimpleString -- execute Python source code
        from a string in __main__
      * setupVirtualEnvironment -- set up a
        virtual environment
      * toFunction -- convert callable python objects to
        Macaulay2 functions
      * toPython -- convert Macaulay2 things to Python objects
  * Methods
      * ?? PythonObject -- null coalescing operator for
        Python objects
      * abs(PythonObject) -- absolute value of a
        python object
      * acos(PythonObject) -- arc cosine of a
        python object
      * acosh(PythonObject) -- inverse
        hyperbolic cosine of a python object
      * "addPyToM2Function(List,Function,String)" -- see
        addPyToM2Function, -- convenience function for
        adding value hooks
      * "addPyToM2Function(PythonObject,Function,String)" -- see
        addPyToM2Function, -- convenience function for
        adding value hooks
      * "addPyToM2Function(String,Function,String)" -- see
        addPyToM2Function, -- convenience function for
        adding value hooks
      * asin(PythonObject) -- arc sine of a
        python object
      * asinh(PythonObject) -- inverse
        hyperbolic sine of a python object
      * atan(PythonObject) -- arc tangent of a
        python object
      * atan2(PythonObject,PythonObject)
        -- arc tangent of quotient of
        python objects
      * "atan2(PythonObject,Thing)" -- see
        atan2(PythonObject,PythonObject),
        -- arc tangent of quotient of
        python objects
      * "atan2(Thing,PythonObject)" -- see
        atan2(PythonObject,PythonObject),
        -- arc tangent of quotient of
        python objects
      * atanh(PythonObject) -- inverse
        hyperbolic tangent of a python object
      * binomial(PythonObject,PythonObject)
        -- binomial coefficient for
        Python objects
      * "binomial(PythonObject,Thing)" -- see
        binomial(PythonObject,PythonObject),
        -- binomial coefficient for
        Python objects
      * "binomial(Thing,PythonObject)" -- see
        binomial(PythonObject,PythonObject),
        -- binomial coefficient for
        Python objects
      * ceiling(PythonObject) -- ceiling of a
        python object
      * cos(PythonObject) -- cosine of a python
        object
      * cosh(PythonObject) -- hyperbolic cosine
        of a python object
      * delete(Thing,PythonObject), --
        delete elements from mutable python sequences
      * erf(PythonObject) -- error function of a
        python object
      * erfc(PythonObject) -- complementary
        error function of a python object
      * exp(PythonObject) -- exponential of a
        python object
      * expm1(PythonObject) -- exponential
        minus one of a python object
      * floor(PythonObject) -- floor of a
        python object
      * Gamma(PythonObject) -- gamma function
        of a python object
      * "gcd(PythonObject)" -- see gcd(PythonObject,PythonObject),
        -- greatest common divisor of
        Python objects
      * gcd(PythonObject,PythonObject)
        -- greatest common divisor of
        Python objects
      * "gcd(PythonObject,Thing)" -- see gcd(PythonObject,PythonObject),
        -- greatest common divisor of
        Python objects
      * "gcd(Thing,PythonObject)" -- see gcd(PythonObject,PythonObject),
        -- greatest common divisor of
        Python objects
      * help(PythonObject) -- documentation for
        python object
      * "import(String)" -- see import, -- import a Python module
      * "toPython(Matrix)" -- see installNumPyMethods,
        -- install NumPy methods
      * "toPython(MutableMatrix)" -- see installNumPyMethods,
        -- install NumPy methods
      * "toPython(Vector)" -- see installNumPyMethods,
        -- install NumPy methods
      * isFinite(PythonObject) -- whether a
        Python object is finite
      * isInfinite(PythonObject), --
        whether a Python object is infinite
      * isMember(PythonObject,PythonObject)
        -- test membership in a
        python object
      * "isMember(PythonObject,Thing)" -- see
        isMember(PythonObject,PythonObject),
        -- test membership in a
        python object
      * "isMember(Thing,PythonObject)" -- see
        isMember(PythonObject,PythonObject),
        -- test membership in a
        python object
      * iterator(PythonObject) -- get
        iterator of iterable python object
      * "lcm(PythonObject)" -- see lcm(PythonObject,PythonObject),
        -- least common multiple of
        Python objects
      * lcm(PythonObject,PythonObject)
        -- least common multiple of
        Python objects
      * "lcm(PythonObject,Thing)" -- see lcm(PythonObject,PythonObject),
        -- least common multiple of
        Python objects
      * "lcm(Thing,PythonObject)" -- see lcm(PythonObject,PythonObject),
        -- least common multiple of
        Python objects
      * length(PythonObject) -- returns the
        length of a python object
      * listSymbols(PythonContext), --
        get a table of all the variables and their values in a python context
      * "listSymbols(PythonObject)" -- see listSymbols(PythonContext),
        -- get a table of all the variables and
        their values in a python context
      * lngamma(PythonObject) -- natural
        logarithm of the gamma function of a python object
      * "log(PythonObject)" -- see log(PythonObject,PythonObject),
        -- logarithm of a python object
      * log(PythonObject,PythonObject)
        -- logarithm of a python object
      * "log(PythonObject,Thing)" -- see log(PythonObject,PythonObject),
        -- logarithm of a python object
      * "log(Thing,PythonObject)" -- see log(PythonObject,PythonObject),
        -- logarithm of a python object
      * log1p(PythonObject) -- logarithm plus
        one of a python object
      * next(PythonObject) -- retrieve the next
        item from a python iterator
      * not PythonObject -- logical negation of a
        python object
      * "pipInstall(String)" -- see pipInstall, -- install a
        Python package
      * "new PythonContext" -- see PythonContext, --
        persistent Python execution environment
      * "new PythonContext from String" -- see PythonContext,
        -- persistent Python execution environment
      * "PythonContext String" -- see PythonContext, --
        persistent Python execution environment
      * PythonContext _ String -- get value of
        variable in a python context
      * PythonObject ! -- factorial of a Python object
      * PythonObject % PythonObject -- the
        modulo operator for Python objects
      * "PythonObject % Thing" -- see PythonObject % PythonObject,
        -- the modulo operator for Python objects
      * "Thing % PythonObject" -- see PythonObject % PythonObject,
        -- the modulo operator for Python objects
      * PythonObject %= Thing -- augmented modulo
        operator for Python objects
      * PythonObject & PythonObject, --
        bitwise conjunction of Python objects
      * "PythonObject & Thing" -- see PythonObject & PythonObject,
        -- bitwise conjunction of Python objects
      * "Thing & PythonObject" -- see PythonObject & PythonObject,
        -- bitwise conjunction of Python objects
      * PythonObject &= Thing -- augmented
        bitwise conjunction of Python objects
      * PythonObject * PythonObject, --
        multiply Python objects
      * "PythonObject * Thing" -- see PythonObject * PythonObject,
        -- multiply Python objects
      * "Thing * PythonObject" -- see PythonObject * PythonObject,
        -- multiply Python objects
      * PythonObject *= Thing -- augmented
        multiplication of Python objects
      * "+ PythonObject" -- see PythonObject + PythonObject,
        -- add Python objects
      * PythonObject + PythonObject -- add
        Python objects
      * "PythonObject + Thing" -- see PythonObject + PythonObject,
        -- add Python objects
      * "Thing + PythonObject" -- see PythonObject + PythonObject,
        -- add Python objects
      * PythonObject += Thing -- augmented
        addition of Python objects
      * "- PythonObject" -- see PythonObject - PythonObject,
        -- subtract Python objects
      * PythonObject - PythonObject, --
        subtract Python objects
      * "PythonObject - Thing" -- see PythonObject - PythonObject,
        -- subtract Python objects
      * "Thing - PythonObject" -- see PythonObject - PythonObject,
        -- subtract Python objects
      * PythonObject -= Thing -- augmented
        subtraction of Python objects
      * PythonObject / PythonObject -- true
        division of Python objects
      * "PythonObject / Thing" -- see PythonObject / PythonObject,
        -- true division of Python objects
      * "Thing / PythonObject" -- see PythonObject / PythonObject,
        -- true division of Python objects
      * PythonObject // PythonObject, --
        floor division of Python objects
      * "PythonObject // Thing" -- see PythonObject // PythonObject,
        -- floor division of Python objects
      * "Thing // PythonObject" -- see PythonObject // PythonObject,
        -- floor division of Python objects
      * PythonObject //= Thing -- augmented
        floor division of Python objects
      * PythonObject /= Thing -- augmented true
        division of Python objects
      * PythonObject << PythonObject, --
        the left shift operator for Python objects
      * "PythonObject << Thing" -- see PythonObject << PythonObject,
        -- the left shift operator for Python
        objects
      * "Thing << PythonObject" -- see PythonObject << PythonObject,
        -- the left shift operator for Python
        objects
      * PythonObject <<= Thing -- augmented left
        shift for Python objects
      * PythonObject == PythonObject, --
        equality of Python objects
      * "PythonObject == Thing" -- see PythonObject == PythonObject,
        -- equality of Python objects
      * "Thing == PythonObject" -- see PythonObject == PythonObject,
        -- equality of Python objects
      * PythonObject >> PythonObject, --
        the right shift operator for Python objects
      * "PythonObject >> Thing" -- see PythonObject >> PythonObject,
        -- the right shift operator for Python
        objects
      * "Thing >> PythonObject" -- see PythonObject >> PythonObject,
        -- the right shift operator for Python
        objects
      * PythonObject >>= Thing -- augmented
        right shift for Python objects
      * PythonObject ? PythonObject, --
        compare Python objects
      * "PythonObject ? Thing" -- see PythonObject ? PythonObject,
        -- compare Python objects
      * "Thing ? PythonObject" -- see PythonObject ? PythonObject,
        -- compare Python objects
      * PythonObject @ PythonObject, --
        matrix multiplication of Python objects
      * "PythonObject @ Thing" -- see PythonObject @ PythonObject,
        -- matrix multiplication of Python objects
      * "Thing @ PythonObject" -- see PythonObject @ PythonObject,
        -- matrix multiplication of Python objects
      * PythonObject @= Thing -- augmented matrix
        multiplication of Python objects
      * PythonObject @@ Thing -- get an attribute
        of a python object
      * PythonObject @@ Thing = Thing, --
        set an attribute of a python object
      * PythonObject @@? Thing -- whether a
        python object has an attribute
      * "PythonObject ** PythonObject" -- see PythonObject ^ PythonObject,
        -- exponentiation of Python
        objects
      * "PythonObject ** Thing" -- see PythonObject ^ PythonObject,
        -- exponentiation of Python objects
      * PythonObject ^ PythonObject, --
        exponentiation of Python objects
      * "PythonObject ^ Thing" -- see PythonObject ^ PythonObject,
        -- exponentiation of Python objects
      * "Thing ** PythonObject" -- see PythonObject ^ PythonObject,
        -- exponentiation of Python objects
      * "Thing ^ PythonObject" -- see PythonObject ^ PythonObject,
        -- exponentiation of Python objects
      * "PythonObject **= Thing" -- see PythonObject ^= Thing,
        -- augmented exponentiation for Python objects
      * PythonObject ^= Thing -- augmented
        exponentiation for Python objects
      * PythonObject ^^ PythonObject, --
        bitwise exclusive disjunction of Python objects
      * "PythonObject ^^ Thing" -- see PythonObject ^^ PythonObject,
        -- bitwise exclusive disjunction of
        Python objects
      * "Thing ^^ PythonObject" -- see PythonObject ^^ PythonObject,
        -- bitwise exclusive disjunction of
        Python objects
      * PythonObject ^^= Thing -- augmented
        bitwise exclusive disjunction of Python objects
      * PythonObject _ Thing -- get elements of
        python sequences
      * PythonObject _ Thing = Thing, --
        set elements of mutable python sequences
      * PythonObject | PythonObject, --
        bitwise disjunction of Python objects
      * "PythonObject | Thing" -- see PythonObject | PythonObject,
        -- bitwise disjunction of Python objects
      * "Thing | PythonObject" -- see PythonObject | PythonObject,
        -- bitwise disjunction of Python objects
      * PythonObject |= Thing -- augmented
        bitwise disjunction of Python objects
      * PythonObject ~ -- bitwise negation of a python
        object
      * PythonObject and PythonObject, --
        logical conjunction of Python objects
      * "PythonObject and Thing" -- see PythonObject and PythonObject,
        -- logical conjunction of Python objects
      * "Thing and PythonObject" -- see PythonObject and PythonObject,
        -- logical conjunction of Python objects
      * PythonObject or PythonObject, --
        logical disjunction of Python objects
      * "PythonObject or Thing" -- see PythonObject or PythonObject,
        -- logical disjunction of Python objects
      * "Thing or PythonObject" -- see PythonObject or PythonObject,
        -- logical disjunction of Python objects
      * PythonObject xor PythonObject, --
        logical exclusive disjunction of Python objects
      * "PythonObject xor Thing" -- see PythonObject xor PythonObject,
        -- logical exclusive disjunction of
        Python objects
      * "Thing xor PythonObject" -- see PythonObject xor PythonObject,
        -- logical exclusive disjunction of
        Python objects
      * "pythonRunScript(Sequence)" -- see pythonRunScript,
        -- execute a sequence of Python statements
      * "pythonRunScript(String)" -- see pythonRunScript,
        -- execute a sequence of Python statements
      * "pythonValue(Sequence)" -- see pythonValue, --
        execute Python source code from a string
      * "pythonValue(String)" -- see pythonValue, -- execute
        Python source code from a string
      * quotientRemainder(PythonObject,PythonObject)
        -- get the quotient
        and remainder when dividing Python objects
      * "quotientRemainder(PythonObject,Thing)" -- see
        quotientRemainder(PythonObject,PythonObject),
        -- get the quotient
        and remainder when dividing Python objects
      * "quotientRemainder(Thing,PythonObject)" -- see
        quotientRemainder(PythonObject,PythonObject),
        -- get the quotient
        and remainder when dividing Python objects
      * remainder(PythonObject,PythonObject)
        -- remainder of python
        objects
      * "remainder(PythonObject,Thing)" -- see
        remainder(PythonObject,PythonObject),
        -- remainder of python
        objects
      * "remainder(Thing,PythonObject)" -- see
        remainder(PythonObject,PythonObject),
        -- remainder of python
        objects
      * "round(PythonObject)" -- see round(PythonObject,PythonObject),
        -- round a python object
      * round(PythonObject,PythonObject)
        -- round a python object
      * "round(PythonObject,Thing)" -- see
        round(PythonObject,PythonObject),
        -- round a python object
      * "round(Thing,PythonObject)" -- see
        round(PythonObject,PythonObject),
        -- round a python object
      * "setupVirtualEnvironment(String)" -- see setupVirtualEnvironment,
        -- set up a virtual environment
      * sin(PythonObject) -- sine of a python
        object
      * sinh(PythonObject) -- hyperbolic sine of
        a python object
      * sqrt(PythonObject) -- square root of a
        python object
      * tan(PythonObject) -- tangent of a python
        object
      * tanh(PythonObject) -- hyperbolic tangent
        of a python object
      * "describe(PythonObject)" -- see toExternalString(PythonObject),
        -- unambiguous string
        representation of a python object
      * toExternalString(PythonObject)
        -- unambiguous string
        representation of a python object
      * "PythonObject Thing" -- see toFunction, -- convert
        callable python objects to Macaulay2 functions
      * "toFunction(PythonObject)" -- see toFunction, --
        convert callable python objects to Macaulay2 functions
      * "toPython(Boolean)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(CC)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(Function)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(HashTable)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Nothing)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Number)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(PythonObject)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(RR)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(RRi)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(Sequence)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Set)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(String)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Symbol)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(VisibleList)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(ZZ)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "expression(PythonObject)" -- see toString(PythonObject),
        -- readable string representation of a
        python object
      * "net(PythonObject)" -- see toString(PythonObject),
        -- readable string representation of a
        python object
      * "texMath(PythonObject)" -- see toString(PythonObject),
        -- readable string representation of a
        python object
      * toString(PythonObject) -- readable
        string representation of a python object
      * truncate(PythonObject) -- truncate a
        python object
      * use(PythonContext) -- install variables
        from a python context
      * value(PythonObject) -- convert python
        objects to Macaulay2 things

For the programmer
==================

The object Python, is a package (Macaulay2Doc),
defined in Python.m2, with auxiliary files in Python/.

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:47:0.

Python tutorial: creating a virtual environment and installing NumPy
********************************************************************

In this tutorial, we demonstrate how to create a Python virtual environment and
install the numpy (see https://numpy.org ) module within it. A virtual
environment allows us to isolate Python packages from the system-wide
installation, ensuring that dependencies do not interfere with other projects.

Step 1: Create a Virtual Environment
====================================

First, we choose a directory where we want to create our virtual environment.
We then call setupVirtualEnvironment, with that
directory. This command initializes a new virtual environment, which includes a
dedicated Python interpreter and an isolated package installation directory.

+------------------------------------------+
|i1 : needsPackage "Python";               |
+------------------------------------------+
|i2 : dir = applicationDirectory() | "venv"|
|                                          |
|o2 = /home/m2user/.Macaulay2/venv         |
+------------------------------------------+
|i3 : setupVirtualEnvironment dir          |
+------------------------------------------+

Step 2: Reload the Python Package with the Virtual Environment
==============================================================

Next we restart Macaulay2 so we can initialize the Python binary in the new
virtual environment.

+------------+
|i4 : restart|
+------------+

To ensure that the Python interface uses the newly created virtual environment,
we load the Python package while specifying the virtual environment’s Python
interpreter. This is done by setting the "executable" configuration option to
point to the python3 binary inside our virtual environment.

+----------------------------------------------------------------------+
|i1 : loadPackage("Python", Configuration => {                         |
|         "executable" => applicationDirectory() | "venv/bin/python3"})|
|                                                                      |
|o1 = Python                                                           |
|                                                                      |
|o1 : Package                                                          |
+----------------------------------------------------------------------+

At this point, all Python commands will use the virtual environment's
interpreter rather than the system-wide Python installation.

Step 3: Install NumPy
=====================

Next, we install the NumPy module using pipInstall. This
downloads and installs NumPy into the virtual environment.

+-----------------------------------------------------------------------------+
|i2 : pipInstall "numpy"                                                      |
|Collecting numpy                                                             |
|  Downloading numpy-2.2.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86|
|     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.0/62.0 kB 2.5 MB/s eta 0:00:|
|                                                                             |
|Downloading numpy-2.2.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_6|
|   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 16.1/16.1 MB 47.9 MB/s eta 0:00:0|
|                                                                             |
|Installing collected packages: numpy                                         |
|Successfully installed numpy-2.2.4                                           |
|-----------------------------------------------------------------------------|
|_64.whl.metadata (62 kB)                                                     |
|00                                                                           |
|                                                                             |
|4.whl (16.1 MB)                                                              |
|0                                                                            |
+-----------------------------------------------------------------------------+

Once this step completes, NumPy is fully installed and ready for use.

Step 4: Import and Use NumPy
============================

Now that NumPy is installed, we can call installNumPyMethods,
and begin using it.  Let's verify that it works by
multiplying two matrices.

+-----------------------------------------------------------------------------+
|i3 : installNumPyMethods()                                                   |
|                                                                             |
|o3 = <module 'numpy' from '/home/profzoom/.Macaulay2/venv/lib/python3.10/site|
|     packages/numpy/__init__.py'>                                            |
|                                                                             |
|o3 : PythonObject of class module                                            |
|-----------------------------------------------------------------------------|
|-                                                                            |
+-----------------------------------------------------------------------------+
|i4 : A = toPython matrix {{1, 2}, {3, 4}}                                    |
|                                                                             |
|o4 = [[1 2]                                                                  |
|      [3 4]]                                                                 |
|                                                                             |
|o4 : PythonObject of class numpy.ndarray                                     |
+-----------------------------------------------------------------------------+
|i5 : B = toPython matrix {{5, 6}, {7, 8}}                                    |
|                                                                             |
|o5 = [[5 6]                                                                  |
|      [7 8]]                                                                 |
|                                                                             |
|o5 : PythonObject of class numpy.ndarray                                     |
+-----------------------------------------------------------------------------+
|i6 : A @ B                                                                   |
|                                                                             |
|o6 = [[19 22]                                                                |
|      [43 50]]                                                               |
|                                                                             |
|o6 : PythonObject of class numpy.ndarray                                     |
+-----------------------------------------------------------------------------+

See also
========

  * setupVirtualEnvironment -- set up a virtual
    environment
  * pipInstall -- install a Python package
  * installNumPyMethods -- install NumPy methods
-------------------------------------------------------------------------------

The source of this document is in Python/doc/tutorials.m2:132:0.

Python tutorial: plotting the twisted cubic with Matplotlib
***********************************************************

In this tutorial, we use Matplotlib (see https://matplotlib.org/ ) to plot the
twisted cubic in three different ways.  We are assuming that Matplotlib is
already installed.  See pipInstall, to learn how to install
Python modules.

This example is heavily inspired by the Parametric curve (see
https://matplotlib.org/stable/gallery/mplot3d/lines3d.html ) example in the
matplotlib documentation.

Running Python code directly
============================

If we just want to run some Python code directly, then the simplest way is with
the pythonRunScript, method.

For this example, we have our code saved as a .py file.

+-------------------------------------------------------------------------+
|i1 : pycode = get(Python#"auxiliary files" | "doc/matplotlib-example.py")|
|                                                                         |
|o1 = import matplotlib.pyplot as plt                                     |
|     import numpy as np                                                  |
|                                                                         |
|     fig = plt.figure()                                                  |
|     ax = fig.add_subplot(projection='3d')                               |
|     t = np.linspace(-10, 10, 100)                                       |
|     ax.plot(t, t**2, t**3)                                              |
|     plt.show()                                                          |
+-------------------------------------------------------------------------+
|i2 : pythonRunScript pycode                                              |
+-------------------------------------------------------------------------+

Using a PythonContext
=====================

See PythonContext, objects allow us to run Python code one
line at a time, just like working in the Python REPL.

+-------------------------------------------------------------------+
|i3 : matplotlib = PythonContext "import matplotlib.pyplot as plt"  |
|                                                                   |
|o3 = matplotlib                                                    |
|                                                                   |
|o3 : PythonContext                                                 |
+-------------------------------------------------------------------+
|i4 : matplotlib "import numpy as np"                               |
+-------------------------------------------------------------------+
|i5 : matplotlib "fig = plt.figure()"                               |
+-------------------------------------------------------------------+
|i6 : matplotlib "ax = fig.add_subplot(projection='3d')"            |
+-------------------------------------------------------------------+
|i7 : matplotlib "t = np.linspace(-10, 10, 100)"                    |
+-------------------------------------------------------------------+
|i8 : matplotlib "ax.plot(t, t**2, t**3)"                           |
|                                                                   |
|o8 = [<mpl_toolkits.mplot3d.art3d.Line3D object at 0x7b8243b7e5f0>]|
|                                                                   |
|o8 : PythonObject of class list                                    |
+-------------------------------------------------------------------+
|i9 : matplotlib "plt.show()"                                       |
|                                                                   |
|o9 = None                                                          |
|                                                                   |
|o9 : PythonObject of class NoneType                                |
+-------------------------------------------------------------------+

Using PythonObjects directly
============================

Finally, we can write our code in the Macaulay2 language, but making calls to
Python as needed.

First, we import the necessary modules using import.  Note that
we can essentially replace the Python import foo as bar with bar = import
"foo".

+-----------------------------------------------------------------------------+
|i10 : plt = import "matplotlib.pyplot"                                       |
|                                                                             |
|o10 = <module 'matplotlib.pyplot' from                                       |
|      '/usr/lib/python3/dist-packages/matplotlib/pyplot.py'>                 |
|                                                                             |
|o10 : PythonObject of class module                                           |
+-----------------------------------------------------------------------------+
|i11 : np = import "numpy"                                                    |
|                                                                             |
|o11 = <module 'numpy' from '/usr/lib/python3/dist-packages/numpy/__init__.py'|
|                                                                             |
|o11 : PythonObject of class module                                           |
|-----------------------------------------------------------------------------|
|>                                                                            |
+-----------------------------------------------------------------------------+

Next, we begin to create the various Python objects needed for our plot.

Note that we replace the Python foo.bar with foo@@bar (see PythonObject @@ Thing).
We need to be careful for attributes that
include underscores. They must given as strings, i.e., delimited using quotes.

+-------------------------------------------------------------------+
|i12 : fig = plt@@figure()                                          |
|                                                                   |
|o12 = Figure(640x480)                                              |
|                                                                   |
|o12 : PythonObject of class matplotlib.figure.Figure               |
+-------------------------------------------------------------------+
|i13 : ax = fig@@"add_subplot"(projection => "3d")                  |
|                                                                   |
|o13 = Axes3DSubplot(0.125,0.11;0.775x0.77)                         |
|                                                                   |
|o13 : PythonObject of class matplotlib.axes._subplots.Axes3DSubplot|
+-------------------------------------------------------------------+
|i14 : t = np@@linspace(-10, 10, 100);                              |
+-------------------------------------------------------------------+

Now we construct the twisted cubic.  Note that even though Python itself uses
** for exponentiation, we may use ^ (Macaulay2Doc), for consistency
with the rest of Macaulay2.

+--------------------------------------------------------------------+
|i15 : ax@@plot(t, t^2, t^3)                                         |
|                                                                    |
|o15 = [<mpl_toolkits.mplot3d.art3d.Line3D object at 0x73a51970eb00>]|
|                                                                    |
|o15 : PythonObject of class list                                    |
+--------------------------------------------------------------------+

Finally, we show our plot.

+-----------------+
|i16 : plt@@show()|
+-----------------+

All three of the above methods should have resulted in a window appearing
containing the following image.

parametric plot of the twisted cubic

-------------------------------------------------------------------------------

The source of this document is in Python/doc/tutorials.m2:288:0.

pythonValue -- execute Python source code from a string
*******************************************************

  * Usage:
        pythonValue s
  * Inputs:
      * s, a string (Macaulay2Doc), or a sequence (Macaulay2Doc),
        containing Python source code;
  * Optional inputs (Macaulay2Doc),:
      * Global => a python object, default value null,
        globals dictionary;
  * Outputs:
      * a python object, the return value of the given
        code;

Description
===========

This function a is wrapper around the function PyRun_String (see
https://docs.python.org/3/c-api/veryhigh.html#c.PyRun_String ) from the Python
C API.

+------------------------------+
|i1 : pythonValue "2 + 2"      |
|                              |
|o1 = 4                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If a sequence is given, then its elements are converted to strings using
toString (Macaulay2Doc), and then joined using concatenate (Macaulay2Doc).
You can see the expression sent to the Python
interpreter by setting debugLevel (Macaulay2Doc), to a
positive value.

+------------------------------+
|i2 : debugLevel = 1           |
|                              |
|o2 = 1                        |
+------------------------------+
|i3 : x = 5                    |
|                              |
|o3 = 5                        |
+------------------------------+
|i4 : pythonValue("3 + ", x)   |
| -- python command: 3 + 5     |
|                              |
|o4 = 8                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+

See also
========

  * runSimpleString -- execute Python source code from
    a string in __main__
  * pythonRunScript -- execute a sequence of Python
    statements

Ways to use pythonValue:
========================

  * "pythonValue(Sequence)"
  * "pythonValue(String)"

For the programmer
==================

The object pythonValue, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:208:0.

pythonRunScript -- execute a sequence of Python statements
**********************************************************

  * Usage:
        pythonRunScript s
  * Inputs:
      * s, a string (Macaulay2Doc), or a sequence (Macaulay2Doc),
        containing Python code;
  * Optional inputs (Macaulay2Doc),:
      * Global => a python object, default value null,
        globals dictionary;
  * Outputs:
      * a python object, the globals dictionary;

Description
===========

Execute a sequence of statements as if they were read from a Python file. This
is for multi-line code that might contain definitions, control structures,
imports, etc.  It is great for running Python code from a file.

The return value is a Python dictionary containing all the variables defined in
the global scope.

+-----------------------------------------------------------------------------+
|i1 : pyfile = temporaryFileName() | ".py"                                    |
|                                                                             |
|o1 = /tmp/M2-177077-0/0.py                                                   |
+-----------------------------------------------------------------------------+
|i2 : pyfile << "import math" << endl                                         |
|                                                                             |
|o2 = /tmp/M2-177077-0/0.py                                                   |
|                                                                             |
|o2 : File                                                                    |
+-----------------------------------------------------------------------------+
|i3 : pyfile << "x = math.sin(3.4)" << endl << close                          |
|                                                                             |
|o3 = /tmp/M2-177077-0/0.py                                                   |
|                                                                             |
|o3 : File                                                                    |
+-----------------------------------------------------------------------------+
|i4 : get pyfile                                                              |
|                                                                             |
|o4 = import math                                                             |
|     x = math.sin(3.4)                                                       |
+-----------------------------------------------------------------------------+
|i5 : pythonRunScript oo                                                      |
|                                                                             |
|o5 = {'math': <module 'math' from                                            |
|     '/usr/lib64/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so'|
|     >, 'x': -0.2555411020268312}                                            |
|                                                                             |
|o5 : PythonObject of class dict                                              |
+-----------------------------------------------------------------------------+

The Global option may be used to pass a globals dictionary so that variables
may be shared between scripts.

+-----------------------------------------------------------------------------+
|i6 : pythonRunScript("y = math.cos(x)", Global => oo)                        |
|                                                                             |
|o6 = {'math': <module 'math' from                                            |
|     '/usr/lib64/python3.12/lib-dynload/math.cpython-312-x86_64-linux-gnu.so'|
|     >, 'x': -0.2555411020268312, 'y': 0.9675266635316214}                   |
|                                                                             |
|o6 : PythonObject of class dict                                              |
+-----------------------------------------------------------------------------+

See also
========

  * pythonValue -- execute Python source code from a string
  * runSimpleString -- execute Python source code from
    a string in __main__

Ways to use pythonRunScript:
============================

  * "pythonRunScript(Sequence)"
  * "pythonRunScript(String)"

For the programmer
==================

The object pythonRunScript, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:270:0.

runSimpleString -- execute Python source code from a string in __main__
***********************************************************************

  * Usage:
        runSimpleString s
  * Inputs:
      * s, a string (Macaulay2Doc), containing Python source
        code;

Description
===========

This function a is wrapper around the function PyRun_SimpleString (see
https://docs.python.org/3/c-api/veryhigh.html#c.PyRun_SimpleString ) from the
Python C API.  Note that, unlike pythonValue, it has no
return value.

+----------------------------------------------+
|i1 : runSimpleString "print('Hello, world!')" |
+----------------------------------------------+

See also
========

  * pythonValue -- execute Python source code from a string
  * pythonRunScript -- execute a sequence of Python
    statements

For the programmer
==================

The object runSimpleString, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:230:0.

setupVirtualEnvironment -- set up a virtual environment
*******************************************************

  * Usage:
        setupVirtualEnvironment dir
  * Inputs:
      * dir, a string (Macaulay2Doc),

Description
===========

This sets up a Python virtual environment.  It is equivalent to calling python3
-m venv dir on the command line.

+------------------------------------------+
|i1 : dir = applicationDirectory() | "venv"|
|                                          |
|o1 = /home/profzoom/.Macaulay2/venv       |
+------------------------------------------+
|i2 : setupVirtualEnvironment dir          |
+------------------------------------------+

Caveat
======

To use the virtual environment, you must restart Macaulay2 and then load the
Python package with the "executable" configuration option set to point to the
Python executable in dir.

See also
========

  * pipInstall -- install a Python package
  * Python tutorial_colon_ creating a virtual environment and installing NumPy

Ways to use setupVirtualEnvironment:
====================================

  * "setupVirtualEnvironment(String)"

For the programmer
==================

The object setupVirtualEnvironment, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc/venv.m2:39:0.

pipInstall -- install a Python package
**************************************

  * Usage:
        pipInstall pkg
  * Inputs:
      * pkg, a string (Macaulay2Doc),

Description
===========

This method installs a Python package.  It is equivalent to calling pip install
pkg on the command line.

You likely want to create a virtual environment first.  See
setupVirtualEnvironment.

Let's suppose that one exists in applicationDirectory() | "venv".

+-----------------------------------------------------------------------------+
|i1 : loadPackage("Python", Configuration => {                                |
|          "executable" => applicationDirectory() | "venv/bin/python3"})      |
|                                                                             |
|o1 = Python                                                                  |
|                                                                             |
|o1 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i2 : pipInstall "matplotlib"                                                 |
|Collecting matplotlib                                                        |
|  Using cached matplotlib-3.10.7-cp310-cp310-manylinux2014_x86_64.manylinux_2|
|Collecting fonttools>=4.22.0                                                 |
|  Using cached fonttools-4.60.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_|
|Collecting packaging>=20.0                                                   |
|  Using cached packaging-25.0-py3-none-any.whl (66 kB)                       |
|Collecting python-dateutil>=2.7                                              |
|  Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)     |
|Collecting cycler>=0.10                                                      |
|  Using cached cycler-0.12.1-py3-none-any.whl (8.3 kB)                       |
|Collecting kiwisolver>=1.3.1                                                 |
|  Using cached kiwisolver-1.4.9-cp310-cp310-manylinux_2_12_x86_64.manylinux20|
|Collecting pyparsing>=3                                                      |
|  Using cached pyparsing-3.2.5-py3-none-any.whl (113 kB)                     |
|Collecting contourpy>=1.0.1                                                  |
|  Using cached contourpy-1.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux201|
|Collecting numpy>=1.23                                                       |
|  Using cached numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x8|
|Collecting pillow>=8                                                         |
|  Using cached pillow-12.0.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28|
|Collecting six>=1.5                                                          |
|  Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)                       |
|Installing collected packages: six, pyparsing, pillow, packaging, numpy, kiwi|
|Successfully installed contourpy-1.3.2 cycler-0.12.1 fonttools-4.60.1 kiwisol|
|-----------------------------------------------------------------------------|
|_17_x86_64.whl (8.7 MB)                                                      |
|                                                                             |
|17_x86_64.whl (4.8 MB)                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|10_x86_64.whl (1.6 MB)                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|4_x86_64.whl (325 kB)                                                        |
|                                                                             |
|6_64.whl (16.8 MB)                                                           |
|                                                                             |
|_x86_64.whl (7.0 MB)                                                         |
|                                                                             |
|                                                                             |
|solver, fonttools, cycler, python-dateutil, contourpy, matplotlib            |
|ver-1.4.9 matplotlib-3.10.7 numpy-2.2.6 packaging-25.0 pillow-12.0.0         |
|-----------------------------------------------------------------------------|
|pyparsing-3.2.5 python-dateutil-2.9.0.post0 six-1.17.0                       |
+-----------------------------------------------------------------------------+
|i3 : import "matplotlib"                                                     |
|                                                                             |
|o3 = <module 'matplotlib' from                                               |
|     '/home/m2user/.Macaulay2/venv/lib/python3.10/site-packages/matplotlib/__|
|     init__.py'>                                                             |
|                                                                             |
|o3 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+

See also
========

  * setupVirtualEnvironment -- set up a virtual
    environment
  * import -- import a Python module
  * Python tutorial_colon_ creating a virtual environment and installing NumPy

Ways to use pipInstall:
=======================

  * "pipInstall(String)"

For the programmer
==================

The object pipInstall, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc/venv.m2:106:0.

installNumPyMethods -- install NumPy methods
********************************************

  * Usage:
        np = installNumPyMethods()
  * Outputs:
      * np, a python object, the NumPy module;

Description
===========

This function loads the NumPy (see https://numpy.org/ ) module and installs
several toPython, and value(PythonObject),
methods for converting back and forth between
Macaulay2 matrices/vectors and NumPy arrays.

+-----------------------------------------------------------------------------+
|i1 : np = installNumPyMethods()                                              |
|                                                                             |
|o1 = <module 'numpy' from '/usr/lib/python3/dist-packages/numpy/__init__.py'>|
|                                                                             |
|o1 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+
|i2 : A = toPython matrix {{1, 2}, {3, 4}}                                    |
|                                                                             |
|o2 = [[1 2]                                                                  |
|      [3 4]]                                                                 |
|                                                                             |
|o2 : PythonObject of class numpy.ndarray                                     |
+-----------------------------------------------------------------------------+
|i3 : v = toPython vector {5, 6, 7}                                           |
|                                                                             |
|o3 = [5 6 7]                                                                 |
|                                                                             |
|o3 : PythonObject of class numpy.ndarray                                     |
+-----------------------------------------------------------------------------+
|i4 : value A                                                                 |
|                                                                             |
|o4 = | 1 2 |                                                                 |
|     | 3 4 |                                                                 |
|                                                                             |
|              2       2                                                      |
|o4 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i5 : value v                                                                 |
|                                                                             |
|o5 = | 5 |                                                                   |
|     | 6 |                                                                   |
|     | 7 |                                                                   |
|                                                                             |
|       3                                                                     |
|o5 : ZZ                                                                      |
+-----------------------------------------------------------------------------+

The output of the call to installNumPyMethods is a PythonObject,
referring to the module itself and can be used to call NumPy
functions directly.

+----------------------------------------+
|i6 : np@@arange(2, 9, 2)                |
|                                        |
|o6 = [2 4 6 8]                          |
|                                        |
|o6 : PythonObject of class numpy.ndarray|
+----------------------------------------+

For the programmer
==================

The object installNumPyMethods, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc/numpy.m2:77:0.

import -- import a Python module
********************************

  * Usage:
        import s
  * Inputs:
      * s, a string (Macaulay2Doc), the name of a python module;
  * Outputs:
      * a python object, the imported module;

Description
===========

This is a wrapper around the Python C API function PyImport_ImportModule (see
https://docs.python.org/3/c-api/import.html#c.PyImport_ImportModule ) and
returns an imported Python module.

Once imported, the statements and definitions from the module are available
using PythonObject @@ Thing.

+-----------------------------------------------------------------------------+
|i1 : math = import "math"                                                    |
|                                                                             |
|o1 = <module 'math' from '/usr/lib64/python3.12/lib-dynload/math.cpython-312-|
|     x86_64-linux-gnu.so'>                                                   |
|                                                                             |
|o1 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+
|i2 : math@@pi                                                                |
|                                                                             |
|o2 = 3.141592653589793                                                       |
|                                                                             |
|o2 : PythonObject of class float                                             |
+-----------------------------------------------------------------------------+
|i3 : math@@sqrt 2                                                            |
|                                                                             |
|o3 = 1.4142135623730951                                                      |
|                                                                             |
|o3 : PythonObject of class float                                             |
+-----------------------------------------------------------------------------+

Ways to use import:
===================

  * "import(String)"

For the programmer
==================

The object import, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:545:0.

PythonObject -- a Python object
*******************************

Description
===========

In Macaulay2, all Python objects have the class PythonObject. Their Python
classes are displayed after they are printed.

+------------------------------+
|i1 : toPython 3               |
|                              |
|o1 = 3                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : toPython "foo"           |
|                              |
|o2 = foo                      |
|                              |
|o2 : PythonObject of class str|
+------------------------------+

converting to Python objects

converting from Python objects

string functions

list functions

attributes

arithmetic operators

bitwise operators

logical operators

comparison operators

number-theoretic functions

floating-point functions

power, exponential, and logarithmic functions

trigonometric functions

hyperbolic functions

special functions

Methods that use a python object:
=================================

  * ?? PythonObject -- null coalescing operator for
    Python objects
  * abs(PythonObject) -- absolute value of a
    python object
  * acos(PythonObject) -- arc cosine of a python
    object
  * acosh(PythonObject) -- inverse hyperbolic
    cosine of a python object
  * "addPyToM2Function(PythonObject,Function,String)" -- see
    addPyToM2Function, -- convenience function for adding
    value hooks
  * asin(PythonObject) -- arc sine of a python
    object
  * asinh(PythonObject) -- inverse hyperbolic
    sine of a python object
  * atan(PythonObject) -- arc tangent of a
    python object
  * atan2(PythonObject,PythonObject)
    -- arc tangent of quotient of
    python objects
  * "atan2(PythonObject,Thing)" -- see atan2(PythonObject,PythonObject),
    -- arc tangent of quotient of
    python objects
  * "atan2(Thing,PythonObject)" -- see atan2(PythonObject,PythonObject),
    -- arc tangent of quotient of
    python objects
  * atanh(PythonObject) -- inverse hyperbolic
    tangent of a python object
  * binomial(PythonObject,PythonObject)
    -- binomial coefficient for
    Python objects
  * "binomial(PythonObject,Thing)" -- see
    binomial(PythonObject,PythonObject),
    -- binomial coefficient for
    Python objects
  * "binomial(Thing,PythonObject)" -- see
    binomial(PythonObject,PythonObject),
    -- binomial coefficient for
    Python objects
  * ceiling(PythonObject) -- ceiling of a
    python object
  * cos(PythonObject) -- cosine of a python
    object
  * cosh(PythonObject) -- hyperbolic cosine of a
    python object
  * delete(Thing,PythonObject), --
    delete elements from mutable python sequences
  * erf(PythonObject) -- error function of a
    python object
  * erfc(PythonObject) -- complementary error
    function of a python object
  * exp(PythonObject) -- exponential of a python
    object
  * expm1(PythonObject) -- exponential minus
    one of a python object
  * floor(PythonObject) -- floor of a python
    object
  * Gamma(PythonObject) -- gamma function of a
    python object
  * "gcd(PythonObject)" -- see gcd(PythonObject,PythonObject),
    -- greatest common divisor of Python
    objects
  * gcd(PythonObject,PythonObject),
    -- greatest common divisor of Python objects
  * "gcd(PythonObject,Thing)" -- see gcd(PythonObject,PythonObject),
    -- greatest common divisor of Python
    objects
  * "gcd(Thing,PythonObject)" -- see gcd(PythonObject,PythonObject),
    -- greatest common divisor of Python
    objects
  * help(PythonObject) -- documentation for
    python object
  * isFinite(PythonObject) -- whether a
    Python object is finite
  * isInfinite(PythonObject) -- whether a
    Python object is infinite
  * isMember(PythonObject,PythonObject)
    -- test membership in a python
    object
  * "isMember(PythonObject,Thing)" -- see
    isMember(PythonObject,PythonObject),
    -- test membership in a python
    object
  * "isMember(Thing,PythonObject)" -- see
    isMember(PythonObject,PythonObject),
    -- test membership in a python
    object
  * iterator(PythonObject) -- get iterator
    of iterable python object
  * "lcm(PythonObject)" -- see lcm(PythonObject,PythonObject),
    -- least common multiple of Python
    objects
  * lcm(PythonObject,PythonObject),
    -- least common multiple of Python objects
  * "lcm(PythonObject,Thing)" -- see lcm(PythonObject,PythonObject),
    -- least common multiple of Python
    objects
  * "lcm(Thing,PythonObject)" -- see lcm(PythonObject,PythonObject),
    -- least common multiple of Python
    objects
  * length(PythonObject) -- returns the length
    of a python object
  * "listSymbols(PythonObject)" -- see listSymbols(PythonContext),
    -- get a table of all the variables and
    their values in a python context
  * lngamma(PythonObject) -- natural
    logarithm of the gamma function of a python object
  * "log(PythonObject)" -- see log(PythonObject,PythonObject),
    -- logarithm of a python object
  * log(PythonObject,PythonObject),
    -- logarithm of a python object
  * "log(PythonObject,Thing)" -- see log(PythonObject,PythonObject),
    -- logarithm of a python object
  * "log(Thing,PythonObject)" -- see log(PythonObject,PythonObject),
    -- logarithm of a python object
  * log1p(PythonObject) -- logarithm plus one
    of a python object
  * next(PythonObject) -- retrieve the next item
    from a python iterator
  * not PythonObject -- logical negation of a python
    object
  * PythonObject ! -- factorial of a Python object
  * PythonObject % PythonObject -- the
    modulo operator for Python objects
  * "PythonObject % Thing" -- see PythonObject % PythonObject,
    -- the modulo operator for Python objects
  * "Thing % PythonObject" -- see PythonObject % PythonObject,
    -- the modulo operator for Python objects
  * PythonObject %= Thing -- augmented modulo
    operator for Python objects
  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects
  * "PythonObject & Thing" -- see PythonObject & PythonObject,
    -- bitwise conjunction of Python objects
  * "Thing & PythonObject" -- see PythonObject & PythonObject,
    -- bitwise conjunction of Python objects
  * PythonObject &= Thing -- augmented bitwise
    conjunction of Python objects
  * PythonObject * PythonObject, --
    multiply Python objects
  * "PythonObject * Thing" -- see PythonObject * PythonObject,
    -- multiply Python objects
  * "Thing * PythonObject" -- see PythonObject * PythonObject,
    -- multiply Python objects
  * PythonObject *= Thing -- augmented
    multiplication of Python objects
  * "+ PythonObject" -- see PythonObject + PythonObject,
    -- add Python objects
  * PythonObject + PythonObject -- add
    Python objects
  * "PythonObject + Thing" -- see PythonObject + PythonObject,
    -- add Python objects
  * "Thing + PythonObject" -- see PythonObject + PythonObject,
    -- add Python objects
  * PythonObject += Thing -- augmented addition
    of Python objects
  * "- PythonObject" -- see PythonObject - PythonObject,
    -- subtract Python objects
  * PythonObject - PythonObject -- subtract
    Python objects
  * "PythonObject - Thing" -- see PythonObject - PythonObject,
    -- subtract Python objects
  * "Thing - PythonObject" -- see PythonObject - PythonObject,
    -- subtract Python objects
  * PythonObject -= Thing -- augmented
    subtraction of Python objects
  * PythonObject / PythonObject -- true
    division of Python objects
  * "PythonObject / Thing" -- see PythonObject / PythonObject,
    -- true division of Python objects
  * "Thing / PythonObject" -- see PythonObject / PythonObject,
    -- true division of Python objects
  * PythonObject // PythonObject -- floor
    division of Python objects
  * "PythonObject // Thing" -- see PythonObject // PythonObject,
    -- floor division of Python objects
  * "Thing // PythonObject" -- see PythonObject // PythonObject,
    -- floor division of Python objects
  * PythonObject //= Thing -- augmented floor
    division of Python objects
  * PythonObject /= Thing -- augmented true
    division of Python objects
  * PythonObject << PythonObject -- the
    left shift operator for Python objects
  * "PythonObject << Thing" -- see PythonObject << PythonObject,
    -- the left shift operator for Python objects
  * "Thing << PythonObject" -- see PythonObject << PythonObject,
    -- the left shift operator for Python objects
  * PythonObject <<= Thing -- augmented left
    shift for Python objects
  * PythonObject == PythonObject, --
    equality of Python objects
  * "PythonObject == Thing" -- see PythonObject == PythonObject,
    -- equality of Python objects
  * "Thing == PythonObject" -- see PythonObject == PythonObject,
    -- equality of Python objects
  * PythonObject >> PythonObject -- the
    right shift operator for Python objects
  * "PythonObject >> Thing" -- see PythonObject >> PythonObject,
    -- the right shift operator for Python
    objects
  * "Thing >> PythonObject" -- see PythonObject >> PythonObject,
    -- the right shift operator for Python
    objects
  * PythonObject >>= Thing -- augmented right
    shift for Python objects
  * PythonObject ? PythonObject -- compare
    Python objects
  * "PythonObject ? Thing" -- see PythonObject ? PythonObject,
    -- compare Python objects
  * "Thing ? PythonObject" -- see PythonObject ? PythonObject,
    -- compare Python objects
  * PythonObject @ PythonObject -- matrix
    multiplication of Python objects
  * "PythonObject @ Thing" -- see PythonObject @ PythonObject,
    -- matrix multiplication of Python objects
  * "Thing @ PythonObject" -- see PythonObject @ PythonObject,
    -- matrix multiplication of Python objects
  * PythonObject @= Thing -- augmented matrix
    multiplication of Python objects
  * PythonObject @@ Thing -- get an attribute of
    a python object
  * PythonObject @@ Thing = Thing -- set
    an attribute of a python object
  * PythonObject @@? Thing -- whether a python
    object has an attribute
  * "PythonObject ** PythonObject" -- see PythonObject ^ PythonObject,
    -- exponentiation of Python objects
  * "PythonObject ** Thing" -- see PythonObject ^ PythonObject,
    -- exponentiation of Python objects
  * PythonObject ^ PythonObject, --
    exponentiation of Python objects
  * "PythonObject ^ Thing" -- see PythonObject ^ PythonObject,
    -- exponentiation of Python objects
  * "Thing ** PythonObject" -- see PythonObject ^ PythonObject,
    -- exponentiation of Python objects
  * "Thing ^ PythonObject" -- see PythonObject ^ PythonObject,
    -- exponentiation of Python objects
  * "PythonObject **= Thing" -- see PythonObject ^= Thing,
    -- augmented exponentiation for Python objects
  * PythonObject ^= Thing -- augmented
    exponentiation for Python objects
  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * "PythonObject ^^ Thing" -- see PythonObject ^^ PythonObject,
    -- bitwise exclusive disjunction of Python
    objects
  * "Thing ^^ PythonObject" -- see PythonObject ^^ PythonObject,
    -- bitwise exclusive disjunction of Python
    objects
  * PythonObject ^^= Thing -- augmented bitwise
    exclusive disjunction of Python objects
  * PythonObject _ Thing -- get elements of
    python sequences
  * PythonObject _ Thing = Thing -- set
    elements of mutable python sequences
  * PythonObject | PythonObject -- bitwise
    disjunction of Python objects
  * "PythonObject | Thing" -- see PythonObject | PythonObject,
    -- bitwise disjunction of Python objects
  * "Thing | PythonObject" -- see PythonObject | PythonObject,
    -- bitwise disjunction of Python objects
  * PythonObject |= Thing -- augmented bitwise
    disjunction of Python objects
  * PythonObject ~ -- bitwise negation of a python
    object
  * PythonObject and PythonObject, --
    logical conjunction of Python objects
  * "PythonObject and Thing" -- see PythonObject and PythonObject,
    -- logical conjunction of Python objects
  * "Thing and PythonObject" -- see PythonObject and PythonObject,
    -- logical conjunction of Python objects
  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * "PythonObject or Thing" -- see PythonObject or PythonObject,
    -- logical disjunction of Python objects
  * "Thing or PythonObject" -- see PythonObject or PythonObject,
    -- logical disjunction of Python objects
  * PythonObject xor PythonObject, --
    logical exclusive disjunction of Python objects
  * "PythonObject xor Thing" -- see PythonObject xor PythonObject,
    -- logical exclusive disjunction of Python
    objects
  * "Thing xor PythonObject" -- see PythonObject xor PythonObject,
    -- logical exclusive disjunction of Python
    objects
  * quotientRemainder(PythonObject,PythonObject)
    -- get the quotient and
    remainder when dividing Python objects
  * "quotientRemainder(PythonObject,Thing)" -- see
    quotientRemainder(PythonObject,PythonObject),
    -- get the quotient and
    remainder when dividing Python objects
  * "quotientRemainder(Thing,PythonObject)" -- see
    quotientRemainder(PythonObject,PythonObject),
    -- get the quotient and
    remainder when dividing Python objects
  * remainder(PythonObject,PythonObject)
    -- remainder of python objects
  * "remainder(PythonObject,Thing)" -- see
    remainder(PythonObject,PythonObject),
    -- remainder of python objects
  * "remainder(Thing,PythonObject)" -- see
    remainder(PythonObject,PythonObject),
    -- remainder of python objects
  * "round(PythonObject)" -- see round(PythonObject,PythonObject),
    -- round a python object
  * round(PythonObject,PythonObject)
    -- round a python object
  * "round(PythonObject,Thing)" -- see round(PythonObject,PythonObject),
    -- round a python object
  * "round(Thing,PythonObject)" -- see round(PythonObject,PythonObject),
    -- round a python object
  * sin(PythonObject) -- sine of a python object
  * sinh(PythonObject) -- hyperbolic sine of a
    python object
  * sqrt(PythonObject) -- square root of a
    python object
  * tan(PythonObject) -- tangent of a python
    object
  * tanh(PythonObject) -- hyperbolic tangent of
    a python object
  * "describe(PythonObject)" -- see toExternalString(PythonObject),
    -- unambiguous string representation of
    a python object
  * toExternalString(PythonObject),
    -- unambiguous string representation of a python object
  * "PythonObject Thing" -- see toFunction, -- convert
    callable python objects to Macaulay2 functions
  * "toFunction(PythonObject)" -- see toFunction, -- convert
    callable python objects to Macaulay2 functions
  * "toPython(PythonObject)" -- see toPython, -- convert
    Macaulay2 things to Python objects
  * "expression(PythonObject)" -- see toString(PythonObject),
    -- readable string representation of a python
    object
  * "net(PythonObject)" -- see toString(PythonObject),
    -- readable string representation of a python
    object
  * "texMath(PythonObject)" -- see toString(PythonObject),
    -- readable string representation of a python
    object
  * toString(PythonObject) -- readable
    string representation of a python object
  * truncate(PythonObject) -- truncate a
    python object
  * value(PythonObject) -- convert python
    objects to Macaulay2 things

For the programmer
==================

The object PythonObject, is a type (Macaulay2Doc),
with ancestor class Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:159:0.

toPython -- convert Macaulay2 things to Python objects
******************************************************

  * Usage:
        toPython x
  * Inputs:
      * x, a thing (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

Attempt to convert a Macaulay2 thing to a Python object.

+--------------------------------------------------------------------+
|i1 : toPython 2                                                     |
|                                                                    |
|o1 = 2                                                              |
|                                                                    |
|o1 : PythonObject of class int                                      |
+--------------------------------------------------------------------+
|i2 : toPython (1/2)                                                 |
|                                                                    |
|o2 = 0.5                                                            |
|                                                                    |
|o2 : PythonObject of class float                                    |
+--------------------------------------------------------------------+
|i3 : toPython pi                                                    |
|                                                                    |
|o3 = 3.141592653589793                                              |
|                                                                    |
|o3 : PythonObject of class float                                    |
+--------------------------------------------------------------------+
|i4 : toPython ii                                                    |
|                                                                    |
|o4 = 1j                                                             |
|                                                                    |
|o4 : PythonObject of class complex                                  |
+--------------------------------------------------------------------+
|i5 : toPython "foo"                                                 |
|                                                                    |
|o5 = foo                                                            |
|                                                                    |
|o5 : PythonObject of class str                                      |
+--------------------------------------------------------------------+
|i6 : toPython {1, 2, 3, 4}                                          |
|                                                                    |
|o6 = [1, 2, 3, 4]                                                   |
|                                                                    |
|o6 : PythonObject of class list                                     |
+--------------------------------------------------------------------+
|i7 : toPython (1, 2, 3, 4)                                          |
|                                                                    |
|o7 = (1, 2, 3, 4)                                                   |
|                                                                    |
|o7 : PythonObject of class tuple                                    |
+--------------------------------------------------------------------+
|i8 : toPython hashTable {"foo" => "bar"}                            |
|                                                                    |
|o8 = {'foo': 'bar'}                                                 |
|                                                                    |
|o8 : PythonObject of class dict                                     |
+--------------------------------------------------------------------+
|i9 : toPython set {1, 2, 3, 4}                                      |
|                                                                    |
|o9 = {1, 2, 3, 4}                                                   |
|                                                                    |
|o9 : PythonObject of class set                                      |
+--------------------------------------------------------------------+
|i10 : toPython true                                                 |
|                                                                    |
|o10 = True                                                          |
|                                                                    |
|o10 : PythonObject of class bool                                    |
+--------------------------------------------------------------------+
|i11 : toPython null                                                 |
|                                                                    |
|o11 = None                                                          |
|                                                                    |
|o11 : PythonObject of class NoneType                                |
+--------------------------------------------------------------------+
|i12 : m2sqrt = x -> (                                               |
|          print "calling Macaulay2 code from Python!";              |
|          sqrt x)                                                   |
|                                                                    |
|o12 = m2sqrt                                                        |
|                                                                    |
|o12 : FunctionClosure                                               |
+--------------------------------------------------------------------+
|i13 : pysqrt = toPython m2sqrt                                      |
|                                                                    |
|o13 = <built-in method m2sqrt of PyCapsule object at 0x7f809fe31a40>|
|                                                                    |
|o13 : PythonObject of class builtin_function_or_method              |
+--------------------------------------------------------------------+
|i14 : pysqrt 2                                                      |
|calling Macaulay2 code from Python!                                 |
|                                                                    |
|o14 = 1.4142135623730951                                            |
|                                                                    |
|o14 : PythonObject of class float                                   |
+--------------------------------------------------------------------+

Ways to use toPython:
=====================

  * "toPython(Matrix)" -- see installNumPyMethods,
    -- install NumPy methods
  * "toPython(MutableMatrix)" -- see installNumPyMethods,
    -- install NumPy methods
  * "toPython(Vector)" -- see installNumPyMethods,
    -- install NumPy methods
  * "toPython(Boolean)"
  * "toPython(CC)"
  * "toPython(Function)"
  * "toPython(HashTable)"
  * "toPython(Nothing)"
  * "toPython(Number)"
  * "toPython(PythonObject)"
  * "toPython(RR)"
  * "toPython(RRi)"
  * "toPython(Sequence)"
  * "toPython(Set)"
  * "toPython(String)"
  * "toPython(Symbol)"
  * "toPython(VisibleList)"
  * "toPython(ZZ)"

For the programmer
==================

The object toPython, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:519:0.

value(PythonObject) -- convert python objects to Macaulay2 things
*****************************************************************

  * Function: value (Macaulay2Doc),
  * Usage:
        value x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a thing (Macaulay2Doc), the Macaulay2 equivalent of x;

Description
===========

This function attempts to convert x to its corresponding Macaulay2 equivalent.

+--------------------------------------------------------------------+
|i1 : value pythonValue "[1, 3.14159, 'foo', (1,2,3), {'foo':'bar'}]"|
|                                                                    |
|o1 = {1, 3.14159, foo, (1, 2, 3), HashTable{"foo" => bar}}          |
|                                                                    |
|o1 : List                                                           |
+--------------------------------------------------------------------+
|i2 : class \ oo                                                     |
|                                                                    |
|o2 = {ZZ, RR, String, Sequence, HashTable}                          |
|                                                                    |
|o2 : List                                                           |
+--------------------------------------------------------------------+

Since the type of x is not initially known, a sequence of hooks (Macaulay2Doc),
are used to determine its type and then convert it.

+-----------------------------------------------------------------------------+
|i3 : hooks value                                                             |
|                                                                             |
|o3 = {0 => (value, PythonObject, Strategy =>                                 |
|     {1 => (value, PythonObject, Strategy =>                                 |
|     {2 => (value, PythonObject, Strategy =>                                 |
|     {3 => (value, PythonObject, Strategy =>                                 |
|     {4 => (value, PythonObject, Strategy =>                                 |
|     {5 => (value, PythonObject, Strategy =>                                 |
|     {6 => (value, PythonObject, Strategy =>                                 |
|     {7 => (value, PythonObject, Strategy =>                                 |
|     {8 => (value, PythonObject, Strategy =>                                 |
|     {9 => (value, PythonObject, Strategy =>                                 |
|     {10 => (value, PythonObject, Strategy =>                                |
|                                                                             |
|o3 : NumberedVerticalList                                                    |
|-----------------------------------------------------------------------------|
|unknown -> PythonObject)                    }                                |
|collections.abc.Callable -> FunctionClosure)}                                |
|collections.abc.Mapping -> HashTable)       }                                |
|collections.abc.Set -> Set)                 }                                |
|collections.abc.Sequence -> Sequence)       }                                |
|collections.abc.MutableSequence -> List)    }                                |
|str -> String)                              }                                |
|numbers.Complex -> CC)                      }                                |
|numbers.Real -> RR)                         }                                |
|numbers.Integral -> ZZ)                     }                                |
| bool -> Boolean)                           }                                |
+-----------------------------------------------------------------------------+

If no conversion can be done, then x is returned.

Users may add additional hooks using addHook (Macaulay2Doc), or
the convenience function addPyToM2Function.

Ways to use this method:
========================

  * value(PythonObject) -- convert python
    objects to Macaulay2 things
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:431:0.

toFunction -- convert callable python objects to Macaulay2 functions
********************************************************************

  * Usage:
        toFunction x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a function closure (Macaulay2Doc),

Description
===========

This function will convert a Python object into a Macaulay2 function.

+-----------------------------------------------------------------------------+
|i1 : math = import "math"                                                    |
|                                                                             |
|o1 = <module 'math' from '/usr/lib64/python3.12/lib-dynload/math.cpython-312-|
|     x86_64-linux-gnu.so'>                                                   |
|                                                                             |
|o1 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+
|i2 : pysqrt = toFunction math@@sqrt                                          |
|                                                                             |
|o2 = pysqrt                                                                  |
|                                                                             |
|o2 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i3 : pysqrt 2                                                                |
|                                                                             |
|o3 = 1.4142135623730951                                                      |
|                                                                             |
|o3 : PythonObject of class float                                             |
+-----------------------------------------------------------------------------+

Optional arguments can be provided using options.

+-----------------------------------+
|i4 : builtins = import "builtins"  |
|                                   |
|o4 = <module 'builtins' (built-in)>|
|                                   |
|o4 : PythonObject of class module  |
+-----------------------------------+
|i5 : int = toFunction builtins@@int|
|                                   |
|o5 = int                           |
|                                   |
|o5 : FunctionClosure               |
+-----------------------------------+
|i6 : int("deadbeef", "base" => 16) |
|                                   |
|o6 = 3735928559                    |
|                                   |
|o6 : PythonObject of class int     |
+-----------------------------------+

If a python object and a Macaulay2 thing are separated by a space, then
toFunction will be called on the python object and then resulting function will
be called with the Macaulay2 object as its argument.

+--------------------------------+
|i7 : math@@cos pi               |
|                                |
|o7 = -1.0                       |
|                                |
|o7 : PythonObject of class float|
+--------------------------------+

Ways to use toFunction:
=======================

  * "toFunction(PythonObject)"

For the programmer
==================

The object toFunction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:359:0.

addPyToM2Function -- convenience function for adding value hooks
****************************************************************

  * Usage:
        addPyToM2Function(type, f, desc)
  * Inputs:
      * type, a python object, a string (Macaulay2Doc),
        or a list (Macaulay2Doc), the
        type(s) to convert;
      * f, a function (Macaulay2Doc), the function that will do
        the converting;
      * desc, a string (Macaulay2Doc), passed to the Strategy
        option of addHook (Macaulay2Doc),;

Description
===========

Most of the hooks used by value (Macaulay2Doc), have the same
general format: if the python object has a particular type, then use a
particular function to convert it to a corresponding Macaulay2 thing.  This
function simplifies the process of adding such a hook.

For example, suppose we would like to convert Fraction objects from the Python
fractions (see https://docs.python.org/3/library/fractions.html ) module to
QQ (Macaulay2Doc), objects.  Without adding a hook, see value (Macaulay2Doc),
will convert these objects to RR (Macaulay2Doc),
objects.

+-------------------------------------------------------------------+
|i1 : fractions = import "fractions"                                |
|                                                                   |
|o1 = <module 'fractions' from '/usr/lib64/python3.12/fractions.py'>|
|                                                                   |
|o1 : PythonObject of class module                                  |
+-------------------------------------------------------------------+
|i2 : x = fractions@@"Fraction"(2, 3)                               |
|                                                                   |
|o2 = 2/3                                                           |
|                                                                   |
|o2 : PythonObject of class fractions.Fraction                      |
+-------------------------------------------------------------------+
|i3 : value x                                                       |
|                                                                   |
|o3 = .6666666666666666                                             |
|                                                                   |
|o3 : RR (of precision 53)                                          |
+-------------------------------------------------------------------+

So we write a function to do the conversion and then install the hook using
addPyToM2Function.

+-----------------------------------------------------------------------------+
|i4 : toQQ = x -> value x@@"numerator" / value x@@"denominator";              |
+-----------------------------------------------------------------------------+
|i5 : addPyToM2Function("fractions.Fraction", toQQ, "Fraction -> QQ");        |
+-----------------------------------------------------------------------------+
|i6 : value x                                                                 |
|                                                                             |
|     2                                                                       |
|o6 = -                                                                       |
|     3                                                                       |
|                                                                             |
|o6 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i7 : hooks value                                                             |
|                                                                             |
|o7 = {0 => (value, PythonObject, Strategy =>                                 |
|     {1 => (value, PythonObject, Strategy =>                                 |
|     {2 => (value, PythonObject, Strategy =>                                 |
|     {3 => (value, PythonObject, Strategy =>                                 |
|     {4 => (value, PythonObject, Strategy =>                                 |
|     {5 => (value, PythonObject, Strategy =>                                 |
|     {6 => (value, PythonObject, Strategy =>                                 |
|     {7 => (value, PythonObject, Strategy =>                                 |
|     {8 => (value, PythonObject, Strategy =>                                 |
|     {9 => (value, PythonObject, Strategy =>                                 |
|     {10 => (value, PythonObject, Strategy =>                                |
|     {11 => (value, PythonObject, Strategy =>                                |
|                                                                             |
|o7 : NumberedVerticalList                                                    |
|-----------------------------------------------------------------------------|
|unknown -> PythonObject)                    }                                |
|collections.abc.Callable -> FunctionClosure)}                                |
|collections.abc.Mapping -> HashTable)       }                                |
|collections.abc.Set -> Set)                 }                                |
|collections.abc.Sequence -> Sequence)       }                                |
|collections.abc.MutableSequence -> List)    }                                |
|str -> String)                              }                                |
|numbers.Complex -> CC)                      }                                |
|numbers.Real -> RR)                         }                                |
|numbers.Integral -> ZZ)                     }                                |
| bool -> Boolean)                           }                                |
| Fraction -> QQ)                            }                                |
+-----------------------------------------------------------------------------+

Ways to use addPyToM2Function:
==============================

  * "addPyToM2Function(List,Function,String)"
  * "addPyToM2Function(PythonObject,Function,String)"
  * "addPyToM2Function(String,Function,String)"

For the programmer
==================

The object addPyToM2Function, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:471:0.

toString(PythonObject) -- readable string representation of a python object
***************************************************************************

  * Function: toString (Macaulay2Doc),
  * Usage:
        toString x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a string (Macaulay2Doc),

Description
===========

This is equivalent to Python's builtin str function.

+-----------------------------------------------------------------+
|i1 : datetime = import "datetime"                                |
|                                                                 |
|o1 = <module 'datetime' from '/usr/lib64/python3.12/datetime.py'>|
|                                                                 |
|o1 : PythonObject of class module                                |
+-----------------------------------------------------------------+
|i2 : epoch = datetime@@"datetime"(1970, 1, 1)                    |
|                                                                 |
|o2 = 1970-01-01 00:00:00                                         |
|                                                                 |
|o2 : PythonObject of class datetime.datetime                     |
+-----------------------------------------------------------------+
|i3 : toString epoch                                              |
|                                                                 |
|o3 = 1970-01-01 00:00:00                                         |
+-----------------------------------------------------------------+

Note that expression (Macaulay2Doc), net (Macaulay2Doc),
and texMath (Macaulay2Doc), do essentially
the same thing, but return an Expression (Macaulay2Doc), a
Net (Macaulay2Doc), or a string for use in TeX code, respectively.

+---------------------------------+
|i4 : expression epoch            |
|                                 |
|o4 = 1970-01-01 00:00:00         |
|                                 |
|o4 : Expression of class Holder  |
+---------------------------------+
|i5 : net epoch                   |
|                                 |
|o5 = 1970-01-01 00:00:00         |
+---------------------------------+
|i6 : texMath epoch               |
|                                 |
|o6 = \texttt{1970-01-01 00:00:00}|
+---------------------------------+

See also
========

  * toExternalString(PythonObject),
    -- unambiguous string representation of a python object

Ways to use this method:
========================

  * toString(PythonObject) -- readable
    string representation of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/string.m2:33:0.

toExternalString(PythonObject) -- unambiguous string representation of a python object
**************************************************************************************

  * Function: toExternalString (Macaulay2Doc),
  * Usage:
        toExternalString x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a string (Macaulay2Doc),

Description
===========

This returns a string beginning with pythonValue, and that
uses Python's builtin repr function to obtain a string that potentially may be
evaluated using value(String) (Macaulay2Doc), to return
a Python object equal to x.

+-------------------------------------+
|i1 : hello = toPython "Hello, world!"|
|                                     |
|o1 = Hello, world!                   |
|                                     |
|o1 : PythonObject of class str       |
+-------------------------------------+
|i2 : toExternalString hello          |
|                                     |
|o2 = pythonValue "'Hello, world!'"   |
+-------------------------------------+
|i3 : value oo                        |
|                                     |
|o3 = Hello, world!                   |
|                                     |
|o3 : PythonObject of class str       |
+-------------------------------------+

Note that describe (Macaulay2Doc), does essentially the same
thing, but returns a Describe (Macaulay2Doc), object.

+--------------------------------+
|i4 : describe hello             |
|                                |
|o4 = pythonValue 'Hello, world!'|
+--------------------------------+

See also
========

  * toString(PythonObject) -- readable
    string representation of a python object

Ways to use this method:
========================

  * toExternalString(PythonObject),
    -- unambiguous string representation of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/string.m2:64:0.

PythonObject _ Thing -- get elements of python sequences
********************************************************

  * Operator: _ (Macaulay2Doc),
  * Usage:
        x_y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

You may access elements of python sequences using _. This is equivalent to
square brackets ([]) in Python. For example, this works for lists.

+-------------------------------+
|i1 : x = toPython {1, 2, 3, 4} |
|                               |
|o1 = [1, 2, 3, 4]              |
|                               |
|o1 : PythonObject of class list|
+-------------------------------+
|i2 : x_1                       |
|                               |
|o2 = 2                         |
|                               |
|o2 : PythonObject of class int |
+-------------------------------+

It also works for dictionaries.

+------------------------------------------------------+
|i3 : x = toPython hashTable {"spam" => 1, "eggs" => 2}|
|                                                      |
|o3 = {'spam': 1, 'eggs': 2}                           |
|                                                      |
|o3 : PythonObject of class dict                       |
+------------------------------------------------------+
|i4 : x_"eggs"                                         |
|                                                      |
|o4 = 2                                                |
|                                                      |
|o4 : PythonObject of class int                        |
+------------------------------------------------------+

Ways to use this method:
========================

  * PythonObject _ Thing -- get elements of
    python sequences
-------------------------------------------------------------------------------

The source of this document is in Python/doc/list.m2:27:0.

PythonObject _ Thing = Thing -- set elements of mutable python sequences
************************************************************************

  * Operator: _ (Macaulay2Doc),
  * Usage:
        x_y = e
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
      * e, a thing (Macaulay2Doc),

Description
===========

You may set elements of mutable python sequences using _. This is equivalent to
square brackets ([]) in Python. For example, this works for lists.

+-------------------------------+
|i1 : x = toPython {1, 2, 3, 4} |
|                               |
|o1 = [1, 2, 3, 4]              |
|                               |
|o1 : PythonObject of class list|
+-------------------------------+
|i2 : x_0 = 5                   |
|                               |
|o2 = 5                         |
+-------------------------------+
|i3 : x                         |
|                               |
|o3 = [5, 2, 3, 4]              |
|                               |
|o3 : PythonObject of class list|
+-------------------------------+

It also works for dictionaries.

+------------------------------------------------------+
|i4 : x = toPython hashTable {"spam" => 1, "eggs" => 2}|
|                                                      |
|o4 = {'spam': 1, 'eggs': 2}                           |
|                                                      |
|o4 : PythonObject of class dict                       |
+------------------------------------------------------+
|i5 : x_"ham" = 3                                      |
|                                                      |
|o5 = 3                                                |
+------------------------------------------------------+
|i6 : x                                                |
|                                                      |
|o6 = {'spam': 1, 'eggs': 2, 'ham': 3}                 |
|                                                      |
|o6 : PythonObject of class dict                       |
+------------------------------------------------------+

Ways to use this method:
========================

  * PythonObject _ Thing = Thing -- set
    elements of mutable python sequences
-------------------------------------------------------------------------------

The source of this document is in Python/doc/list.m2:55:0.

length(PythonObject) -- returns the length of a python object
*************************************************************

  * Function: length (Macaulay2Doc),
  * Usage:
        length x
  * Inputs:
      * x, a python object,
  * Outputs:
      * an integer (Macaulay2Doc),

Description
===========

This is equivalent the Python len (see
https://docs.python.org/3/library/functions.html#len ) function.

+-------------------------------------+
|i1 : length toPython "Hello, world!" |
|                                     |
|o1 = 13                              |
+-------------------------------------+
|i2 : length pythonValue "[1,2,3,4,5]"|
|                                     |
|o2 = 5                               |
+-------------------------------------+

Ways to use this method:
========================

  * length(PythonObject) -- returns the length
    of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:398:0.

isMember(PythonObject,PythonObject) -- test membership in a python object
*************************************************************************

  * Function: isMember (Macaulay2Doc),
  * Usage:
        isMember(x, y)
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether x is in y;

Description
===========

This tests whether x is a member of y.  This is equivalent to x in y in Python.

+---------------------------------------------+
|i1 : isMember(toPython 3, toPython {1, 2, 3})|
|                                             |
|o1 = true                                    |
+---------------------------------------------+
|i2 : isMember(toPython 4, toPython {1, 2, 3})|
|                                             |
|o2 = false                                   |
+---------------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before testing for membership.

+------------------------------------+
|i3 : isMember(toPython 3, {1, 2, 3})|
|                                    |
|o3 = true                           |
+------------------------------------+
|i4 : isMember(4, toPython {1, 2, 3})|
|                                    |
|o4 = false                          |
+------------------------------------+

When used with dictionaries, which are Python's equivalent of Macaulay2 hash
tables, the keys are tested for membership.  In this sense, it is like the
Macaulay2 #? (Macaulay2Doc), and .? (Macaulay2Doc),
operators.

+---------------------------------------------------------+
|i5 : isMember("foo", toPython hashTable {"foo" => "bar"})|
|                                                         |
|o5 = true                                                |
+---------------------------------------------------------+
|i6 : isMember("bar", toPython hashTable {"foo" => "bar"})|
|                                                         |
|o6 = false                                               |
+---------------------------------------------------------+

Ways to use this method:
========================

  * isMember(PythonObject,PythonObject)
    -- test membership in a python
    object
  * "isMember(PythonObject,Thing)"
  * "isMember(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:679:0.

delete(Thing,PythonObject) -- delete elements from mutable python sequences
***************************************************************************

  * Function: delete (Macaulay2Doc),
  * Usage:
        delete(i, x)
  * Inputs:
      * i, a thing (Macaulay2Doc),
      * x, a python object,

Description
===========

This deletes the element of x indexed by i.  This is equivalent to the del
keyword in Python.

+------------------------------------------------------+
|i1 : x = toPython {3, 5, 7, 9}                        |
|                                                      |
|o1 = [3, 5, 7, 9]                                     |
|                                                      |
|o1 : PythonObject of class list                       |
+------------------------------------------------------+
|i2 : delete(0, x)                                     |
+------------------------------------------------------+
|i3 : x                                                |
|                                                      |
|o3 = [5, 7, 9]                                        |
|                                                      |
|o3 : PythonObject of class list                       |
+------------------------------------------------------+
|i4 : x = toPython hashTable {"spam" => 1, "eggs" => 2}|
|                                                      |
|o4 = {'spam': 1, 'eggs': 2}                           |
|                                                      |
|o4 : PythonObject of class dict                       |
+------------------------------------------------------+
|i5 : delete("eggs", x)                                |
+------------------------------------------------------+
|i6 : x                                                |
|                                                      |
|o6 = {'spam': 1}                                      |
|                                                      |
|o6 : PythonObject of class dict                       |
+------------------------------------------------------+

Ways to use this method:
========================

  * delete(Thing,PythonObject), --
    delete elements from mutable python sequences
-------------------------------------------------------------------------------

The source of this document is in Python/doc/list.m2:78:0.

iterator(PythonObject) -- get iterator of iterable python object
****************************************************************

  * Function: iterator (Macaulay2Doc),
  * Usage:
        i = iterator x
  * Inputs:
      * x, a python object, an iterable;
  * Outputs:
      * i, a python object, an iterator;

Description
===========

This function works just like its Python counterpart (see
https://docs.python.org/3/library/functions.html#iter ).  In particular, i is
an iterator for the iterable object x.

+----------------------------------------------+
|i1 : builtins = import "builtins"             |
|                                              |
|o1 = <module 'builtins' (built-in)>           |
|                                              |
|o1 : PythonObject of class module             |
+----------------------------------------------+
|i2 : x = builtins@@range 3                    |
|                                              |
|o2 = range(0, 3)                              |
|                                              |
|o2 : PythonObject of class range              |
+----------------------------------------------+
|i3 : i = iterator x                           |
|                                              |
|o3 = <range_iterator object at 0x7f809fe4e850>|
|                                              |
|o3 : PythonObject of class range_iterator     |
+----------------------------------------------+

See also
========

  * next(PythonObject) -- retrieve the next item
    from a python iterator

Ways to use this method:
========================

  * iterator(PythonObject) -- get iterator
    of iterable python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:295:0.

next(PythonObject) -- retrieve the next item from a python iterator
*******************************************************************

  * Function: next (Macaulay2Doc),
  * Usage:
        next i
  * Inputs:
      * i, a python object, an iterator;

Description
===========

This function works just like its Python counterpart (see
https://docs.python.org/3/library/functions.html#next ).  In particular, it
retrieves the next item from an iterator.

+----------------------------------------------+
|i1 : builtins = import "builtins"             |
|                                              |
|o1 = <module 'builtins' (built-in)>           |
|                                              |
|o1 : PythonObject of class module             |
+----------------------------------------------+
|i2 : x = builtins@@range 3                    |
|                                              |
|o2 = range(0, 3)                              |
|                                              |
|o2 : PythonObject of class range              |
+----------------------------------------------+
|i3 : i = iterator x                           |
|                                              |
|o3 = <range_iterator object at 0x7f809fe32bb0>|
|                                              |
|o3 : PythonObject of class range_iterator     |
+----------------------------------------------+
|i4 : next i                                   |
|                                              |
|o4 = 0                                        |
|                                              |
|o4 : PythonObject of class int                |
+----------------------------------------------+
|i5 : next i                                   |
|                                              |
|o5 = 1                                        |
|                                              |
|o5 : PythonObject of class int                |
+----------------------------------------------+
|i6 : next i                                   |
|                                              |
|o6 = 2                                        |
|                                              |
|o6 : PythonObject of class int                |
+----------------------------------------------+

When the iterator is exhausted, see StopIteration (Macaulay2Doc),
is returned.

+------------------+
|i7 : next i       |
|                  |
|o7 = StopIteration|
|                  |
|o7 : Symbol       |
+------------------+

See also
========

  * iterator(PythonObject) -- get iterator
    of iterable python object

Ways to use this method:
========================

  * next(PythonObject) -- retrieve the next item
    from a python iterator
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:325:0.

objectType -- type of a python object
*************************************

  * Usage:
        objectType x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the type of x;

Description
===========

This is equivalent to the type (see
https://docs.python.org/3/library/functions.html#type ) function in Python.

+----------------------------------------+
|i1 : objectType toPython 2              |
|                                        |
|o1 = <class 'int'>                      |
|                                        |
|o1 : PythonObject of class type         |
+----------------------------------------+
|i2 : objectType toPython "Hello, world!"|
|                                        |
|o2 = <class 'str'>                      |
|                                        |
|o2 : PythonObject of class type         |
+----------------------------------------+

For the programmer
==================

The object objectType, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:643:0.

PythonObject @@ Thing -- get an attribute of a python object
************************************************************

  * Operator: @@ (Macaulay2Doc),
  * Usage:
        x@@y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

Get an attribute of a Python object.  In Python, the . operator is used.
However, this operator has a special meaning in Macaulay2 and cannot be
overloaded.  Since @@ has similar precedence, it is used instead.

+-----------------------------------+
|i1 : foo = toPython "Hello, world!"|
|                                   |
|o1 = Hello, world!                 |
|                                   |
|o1 : PythonObject of class str     |
+-----------------------------------+
|i2 : foo@@upper()                  |
|                                   |
|o2 = HELLO, WORLD!                 |
|                                   |
|o2 : PythonObject of class str     |
+-----------------------------------+

Note that toString (Macaulay2Doc), is called on y before it is
used. Therefore, symbols and functions may be used as well as strings.
Sometimes, however, it is necessary to use quotes, e.g., when using special
"dunder" methods with double underscores.  These would result in a Macaulay2
syntax error if left unquoted.

+------------------------------+
|i3 : foo@@"__len__"()         |
|                              |
|o3 = 13                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * PythonObject @@ Thing -- get an attribute of
    a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:576:0.

PythonObject @@? Thing -- whether a python object has an attribute
******************************************************************

  * Operator: @@? (Macaulay2Doc),
  * Usage:
        x @@? y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether y is an
        attribute of x;

Description
===========

This is equivalent to the Python hasattr (see
https://docs.python.org/3/library/functions.html#hasattr ) function.

+-----------------------------------+
|i1 : foo = toPython "Hello, world!"|
|                                   |
|o1 = Hello, world!                 |
|                                   |
|o1 : PythonObject of class str     |
+-----------------------------------+
|i2 : foo@@?upper                   |
|                                   |
|o2 = true                          |
+-----------------------------------+
|i3 : foo@@?bar                     |
|                                   |
|o3 = false                         |
+-----------------------------------+

Ways to use this method:
========================

  * PythonObject @@? Thing -- whether a python
    object has an attribute
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:599:0.

PythonObject @@ Thing = Thing -- set an attribute of a python object
********************************************************************

  * Operator: @@ (Macaulay2Doc),
  * Usage:
        x@@y = e
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
      * e, a thing (Macaulay2Doc),

Description
===========

This is equivalent to the Python setattr (see
https://docs.python.org/3/library/functions.html#setattr ) function.  Note that
e is converted to a Python object using toPython.

+-----------------------------------------------------------------------------+
|i1 : math = import "math"                                                    |
|                                                                             |
|o1 = <module 'math' from '/usr/lib64/python3.12/lib-dynload/math.cpython-312-|
|     x86_64-linux-gnu.so'>                                                   |
|                                                                             |
|o1 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+
|i2 : math@@pi = 22/7                                                         |
+-----------------------------------------------------------------------------+
|i3 : math@@pi                                                                |
|                                                                             |
|o3 = 3.142857142857143                                                       |
|                                                                             |
|o3 : PythonObject of class float                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * PythonObject @@ Thing = Thing -- set
    an attribute of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:622:0.

PythonObject + PythonObject -- add Python objects
*************************************************

  * Operator: + (Macaulay2Doc),
  * Usage:
        x + y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the sum of x and y;

Description
===========

Add two Python objects.

+------------------------------+
|i1 : toPython 2 + toPython 3  |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before adding.

+------------------------------+
|i2 : toPython 4 + 5           |
|                              |
|o2 = 9                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 6 + toPython 7           |
|                              |
|o3 = 13                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

It may also be used as a unary method.

+------------------------------+
|i4 : +toPython 6              |
|                              |
|o4 = 6                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject += Thing -- augmented addition
    of Python objects

Ways to use this method:
========================

  * "+ PythonObject"
  * PythonObject + PythonObject -- add
    Python objects
  * "PythonObject + Thing"
  * "Thing + PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:40:0.

PythonObject += Thing -- augmented addition of Python objects
*************************************************************

  * Operator: += (Macaulay2Doc),
  * Usage:
        x += y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the sum of x and y, assigned to
        x;

Description
===========

Add two Python objects and assign the result to the first argument.

+------------------------------+
|i1 : x = toPython 2           |
|                              |
|o1 = 2                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x += toPython 3          |
|                              |
|o2 = 5                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 5                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before adding.

+------------------------------+
|i4 : x = toPython 4           |
|                              |
|o4 = 4                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x += 5                   |
|                              |
|o5 = 9                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 9                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __iadd__ method for in-place addition, then
it will be called.  Otherwise, x and y will be added in the usual way, creating
a new Python object that is assigned back to x.

For example, Python lists support in-place addition.  In the example below, x
is modified directly, and no new object is created.

+-------------------------------+
|i7 : x = toPython {1, 2, 3}    |
|                               |
|o7 = [1, 2, 3]                 |
|                               |
|o7 : PythonObject of class list|
+-------------------------------+
|i8 : x += {4}                  |
|                               |
|o8 = [1, 2, 3, 4]              |
|                               |
|o8 : PythonObject of class list|
+-------------------------------+
|i9 : x                         |
|                               |
|o9 = [1, 2, 3, 4]              |
|                               |
|o9 : PythonObject of class list|
+-------------------------------+

See also
========

  * PythonObject + PythonObject -- add
    Python objects
  * augmented assignment (Macaulay2Doc)

Ways to use this method:
========================

  * PythonObject += Thing -- augmented addition
    of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:83:0.

PythonObject - PythonObject -- subtract Python objects
******************************************************

  * Operator: - (Macaulay2Doc),
  * Usage:
        x - y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the difference of x and y;

Description
===========

Subtract two Python objects.

+------------------------------+
|i1 : toPython 2 - toPython 3  |
|                              |
|o1 = -1                       |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before subtracting.

+------------------------------+
|i2 : toPython 4 - 5           |
|                              |
|o2 = -1                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 6 - toPython 7           |
|                              |
|o3 = -1                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

It may also be used as a unary method.

+------------------------------+
|i4 : -toPython 6              |
|                              |
|o4 = -6                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject -= Thing -- augmented
    subtraction of Python objects

Ways to use this method:
========================

  * "- PythonObject"
  * PythonObject - PythonObject -- subtract
    Python objects
  * "PythonObject - Thing"
  * "Thing - PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:119:0.

PythonObject -= Thing -- augmented subtraction of Python objects
****************************************************************

  * Operator: -= (Macaulay2Doc),
  * Usage:
        x -= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the difference of x and y,
        assigned to x;

Description
===========

Subtract two Python objects and assign the result to the first argument.

+------------------------------+
|i1 : x = toPython 5           |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x -= toPython 3          |
|                              |
|o2 = 2                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 2                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before subtracting.

+------------------------------+
|i4 : x = toPython 9           |
|                              |
|o4 = 9                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x -= 5                   |
|                              |
|o5 = 4                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 4                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __isub__ method for in-place subtraction,
then it will be called.  Otherwise, x and y will be subtracted in the usual
way, creating a new Python object that is assigned back to x.

For example, Python sets support in-place subtraction.  In the example below, x
is modified directly, and no new object is created.

+-------------------------------+
|i7 : x = toPython set {1, 2, 3}|
|                               |
|o7 = {1, 2, 3}                 |
|                               |
|o7 : PythonObject of class set |
+-------------------------------+
|i8 : x -= set {3}              |
|                               |
|o8 = {1, 2}                    |
|                               |
|o8 : PythonObject of class set |
+-------------------------------+
|i9 : x                         |
|                               |
|o9 = {1, 2}                    |
|                               |
|o9 : PythonObject of class set |
+-------------------------------+

See also
========

  * PythonObject - PythonObject -- subtract
    Python objects
  * augmented assignment (Macaulay2Doc)

Ways to use this method:
========================

  * PythonObject -= Thing -- augmented
    subtraction of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:162:0.

PythonObject * PythonObject -- multiply Python objects
******************************************************

  * Operator: * (Macaulay2Doc),
  * Usage:
        x * y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the product of x and y;

Description
===========

Multiply two Python objects.

+------------------------------+
|i1 : toPython 2 * toPython 3  |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before multiplying.

+------------------------------+
|i2 : toPython 4 * 5           |
|                              |
|o2 = 20                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 6 * toPython 7           |
|                              |
|o3 = 42                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject @ PythonObject -- matrix
    multiplication of Python objects
  * PythonObject *= Thing -- augmented
    multiplication of Python objects

Ways to use this method:
========================

  * PythonObject * PythonObject, --
    multiply Python objects
  * "PythonObject * Thing"
  * "Thing * PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:194:0.

PythonObject *= Thing -- augmented multiplication of Python objects
*******************************************************************

  * Operator: *= (Macaulay2Doc),
  * Usage:
        x *= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the product of x and y, assigned
        to x;

Description
===========

Multiply two Python objects and assign the result to the first argument.

+------------------------------+
|i1 : x = toPython 2           |
|                              |
|o1 = 2                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x *= toPython 3          |
|                              |
|o2 = 6                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 6                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before multiplying.

+------------------------------+
|i4 : x = toPython 4           |
|                              |
|o4 = 4                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x *= 5                   |
|                              |
|o5 = 20                       |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 20                       |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __imul__ method for in-place
multiplication, then it will be called.  Otherwise, x and y will be multiplied
in the usual way, creating a new Python object that is assigned back to x.

For example, Python lists support in-place multiplication by an integer (i.e.,
repetition).  In the example below, x is modified directly, and no new object
is created.

+--------------------------------+
|i7 : x = toPython {1, 2, 3}     |
|                                |
|o7 = [1, 2, 3]                  |
|                                |
|o7 : PythonObject of class list |
+--------------------------------+
|i8 : x *= 3                     |
|                                |
|o8 = [1, 2, 3, 1, 2, 3, 1, 2, 3]|
|                                |
|o8 : PythonObject of class list |
+--------------------------------+
|i9 : x                          |
|                                |
|o9 = [1, 2, 3, 1, 2, 3, 1, 2, 3]|
|                                |
|o9 : PythonObject of class list |
+--------------------------------+

See also
========

  * PythonObject * PythonObject, --
    multiply Python objects
  * augmented assignment (Macaulay2Doc)

Ways to use this method:
========================

  * PythonObject *= Thing -- augmented
    multiplication of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:238:0.

PythonObject @ PythonObject -- matrix multiplication of Python objects
**********************************************************************

  * Operator: @ (Macaulay2Doc),
  * Usage:
        x @ y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the product of x and y as
        matrices;

Description
===========

Multiply two Python objects (e.g., NumPy arrays) as matrices.

+-----------------------------------------+
|i1 : installNumPyMethods();              |
+-----------------------------------------+
|i2 : a = toPython matrix {{1, 0}, {0, 1}}|
|                                         |
|o2 = [[1 0]                              |
|      [0 1]]                             |
|                                         |
|o2 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i3 : b = toPython matrix {{4, 1}, {2, 2}}|
|                                         |
|o3 = [[4 1]                              |
|      [2 2]]                             |
|                                         |
|o3 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i4 : a @ b                               |
|                                         |
|o4 = [[4 1]                              |
|      [2 2]]                             |
|                                         |
|o4 : PythonObject of class numpy.ndarray |
+-----------------------------------------+

In Macaulay2, the * operator is used for matrix multiplication, but in NumPy,
this results in componentwise multiplication.

+----------------------------------------+
|i5 : a * b                              |
|                                        |
|o5 = [[4 0]                             |
|      [0 2]]                            |
|                                        |
|o5 : PythonObject of class numpy.ndarray|
+----------------------------------------+

See also
========

  * PythonObject * PythonObject, --
    multiply Python objects
  * PythonObject @= Thing -- augmented matrix
    multiplication of Python objects
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject @ PythonObject -- matrix
    multiplication of Python objects
  * "PythonObject @ Thing"
  * "Thing @ PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:297:0.

PythonObject @= Thing -- augmented matrix multiplication of Python objects
**************************************************************************

  * Operator: @= (Macaulay2Doc),
  * Usage:
        x @= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the product of x and y as
        matrices, assigned to x;

Description
===========

Multiply two Python objects (e.g., NumPy arrays) as matrices and assign the
result to the first argument.

+------------------------------------------+
|i1 : installNumPyMethods();               |
+------------------------------------------+
|i2 : x = toPython matrix {{1, 2}, {3, 4}} |
|                                          |
|o2 = [[1 2]                               |
|      [3 4]]                              |
|                                          |
|o2 : PythonObject of class numpy.ndarray  |
+------------------------------------------+
|i3 : x @= toPython matrix {{5, 6}, {7, 8}}|
|                                          |
|o3 = [[19 22]                             |
|      [43 50]]                            |
|                                          |
|o3 : PythonObject of class numpy.ndarray  |
+------------------------------------------+
|i4 : x                                    |
|                                          |
|o4 = [[19 22]                             |
|     [43 50]]                             |
|                                          |
|o4 : PythonObject of class numpy.ndarray  |
+------------------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before multiplying.

+-----------------------------------------+
|i5 : x = toPython matrix {{1, 2}, {3, 4}}|
|                                         |
|o5 = [[1 2]                              |
|      [3 4]]                             |
|                                         |
|o5 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i6 : x @= matrix {{8, 7}, {6, 5}}        |
|                                         |
|o6 = [[20 17]                            |
|      [48 41]]                           |
|                                         |
|o6 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i7 : x                                   |
|                                         |
|o7 = [[20 17]                            |
|      [48 41]]                           |
|                                         |
|o7 : PythonObject of class numpy.ndarray |
+-----------------------------------------+

If the Python class of x defines an __imatmul__ method for in-place matrix
multiplication, then it will be called.  Otherwise, x and y will be multiplied
in the usual way, creating a new Python object that is assigned back to x.

For example, NumPy arrays support in-place matrix multiplication.  In the
examples above, x was modified directly, and no new objects were created.

See also
========

  * PythonObject @ PythonObject -- matrix
    multiplication of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject @= Thing -- augmented matrix
    multiplication of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:375:0.

PythonObject / PythonObject -- true division of Python objects
**************************************************************

  * Operator: / (Macaulay2Doc),
  * Usage:
        x / y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the true quotient of x and y;

Description
===========

Divide two Python objects, giving the "true" quotient, e.g., when dividing two
integers, the result will be a float.

+--------------------------------+
|i1 : toPython 5 / toPython 3    |
|                                |
|o1 = 1.6666666666666667         |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+--------------------------------+
|i2 : toPython 9 / 5             |
|                                |
|o2 = 1.8                        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+
|i3 : 11 / toPython 7            |
|                                |
|o3 = 1.5714285714285714         |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+

See also
========

  * PythonObject // PythonObject -- floor
    division of Python objects
  * PythonObject /= Thing -- augmented true
    division of Python objects

Ways to use this method:
========================

  * PythonObject / PythonObject -- true
    division of Python objects
  * "PythonObject / Thing"
  * "Thing / PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:408:0.

PythonObject /= Thing -- augmented true division of Python objects
******************************************************************

  * Operator: /= (Macaulay2Doc),
  * Usage:
        x /= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the true quotient of x and y,
        assigned to x;

Description
===========

Divide two Python objects, giving the "true" quotient, e.g., when dividing two
integers, the result will be a float.  Then assign the result to the first
argument.

+--------------------------------+
|i1 : x = toPython 5             |
|                                |
|o1 = 5                          |
|                                |
|o1 : PythonObject of class int  |
+--------------------------------+
|i2 : x /= toPython 3            |
|                                |
|o2 = 1.6666666666666667         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+
|i3 : x                          |
|                                |
|o3 = 1.6666666666666667         |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+--------------------------------+
|i4 : x = toPython 12            |
|                                |
|o4 = 12                         |
|                                |
|o4 : PythonObject of class int  |
+--------------------------------+
|i5 : x /= 5                     |
|                                |
|o5 = 2.4                        |
|                                |
|o5 : PythonObject of class float|
+--------------------------------+
|i6 : x                          |
|                                |
|o6 = 2.4                        |
|                                |
|o6 : PythonObject of class float|
+--------------------------------+

If the Python class of x defines an __itruediv__ method for in-place true
division, then it will be called.  Otherwise, x and y will be divided in the
usual way, creating a new Python object that is assigned back to x.

For example, NumPy arrays support in-place true division.  In the example
below, x is modified  directly, and no new object is created.

+----------------------------------------------+
|i7 : installNumPyMethods();                   |
+----------------------------------------------+
|i8 : x = toPython matrix(RR, {{1, 2}, {3, 4}})|
|                                              |
|o8 = [[1. 2.]                                 |
|      [3. 4.]]                                |
|                                              |
|o8 : PythonObject of class numpy.ndarray      |
+----------------------------------------------+
|i9 : x /= matrix(RR, {{5, 6}, {7, 8}})        |
|                                              |
|o9 = [[0.2        0.33333333]                 |
|      [0.42857143 0.5       ]]                |
|                                              |
|o9 : PythonObject of class numpy.ndarray      |
+----------------------------------------------+
|i10 : x                                       |
|                                              |
|o10 = [[0.2        0.33333333]                |
|       [0.42857143 0.5       ]]               |
|                                              |
|o10 : PythonObject of class numpy.ndarray     |
+----------------------------------------------+

See also
========

  * PythonObject / PythonObject -- true
    division of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject /= Thing -- augmented true
    division of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:473:0.

PythonObject // PythonObject -- floor division of Python objects
****************************************************************

  * Operator: // (Macaulay2Doc),
  * Usage:
        x // y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the floor quotient of x and y;

Description
===========

Divide two Python objects, giving the "floor" quotient, e.g., when dividing two
integers, the result is the quotient using Euclidean division.

+------------------------------+
|i1 : toPython 5 // toPython 3 |
|                              |
|o1 = 1                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+------------------------------+
|i2 : toPython 9 // 5          |
|                              |
|o2 = 1                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 11 // toPython 7         |
|                              |
|o3 = 1                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

Note that the behavior of floor division for integers differs between Macaulay2
and Python.  In particular, in Macaulay2, the quotient is rounded down when y
is positive and up when y is negative.  In Python, the quotient is always
rounded down.

+------------------------------+
|i4 : 5 // -3                  |
|                              |
|o4 = -1                       |
+------------------------------+
|i5 : toPython 5 // -3         |
|                              |
|o5 = -2                       |
|                              |
|o5 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject / PythonObject -- true
    division of Python objects
  * PythonObject % PythonObject -- the
    modulo operator for Python objects
  * quotientRemainder(PythonObject,PythonObject)
    -- get the quotient and
    remainder when dividing Python objects
  * PythonObject //= Thing -- augmented floor
    division of Python objects

Ways to use this method:
========================

  * PythonObject // PythonObject -- floor
    division of Python objects
  * "PythonObject // Thing"
  * "Thing // PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:517:0.

PythonObject //= Thing -- augmented floor division of Python objects
********************************************************************

  * Operator: //= (Macaulay2Doc),
  * Usage:
        x //= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the floor quotient of x and y,
        assigned to x;

Description
===========

Divide two Python objects, giving the "floor" quotient, e.g., when dividing two
integers, the result is the quotient using Euclidean division.  Then assign the
result to the first argument.

+------------------------------+
|i1 : x = toPython 5           |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x //= toPython 3         |
|                              |
|o2 = 1                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 1                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+------------------------------+
|i4 : x = toPython 12          |
|                              |
|o4 = 12                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x //= 5                  |
|                              |
|o5 = 2                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 2                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __ifloordiv__ method for in-place floor
division, then it will be called.  Otherwise, x and y will be divided in the
usual way, creating a new Python object that is assigned back to x.

For example, NumPy arrays support in-place floor division.  In the example
below, x is modified  directly, and no new object is created.

+-----------------------------------------+
|i7 : installNumPyMethods();              |
+-----------------------------------------+
|i8 : x = toPython matrix {{5, 6}, {7, 8}}|
|                                         |
|o8 = [[1 2]                              |
|      [3 4]]                             |
|                                         |
|o8 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i9 : x //= matrix {{1, 2}, {3, 4}}       |
|                                         |
|o9 = [[5 3]                              |
|      [2 2]]                             |
|                                         |
|o9 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i10 : x                                  |
|                                         |
|o10 = [[5 3]                             |
|       [2 2]]                            |
|                                         |
|o10 : PythonObject of class numpy.ndarray|
+-----------------------------------------+

See also
========

  * PythonObject // PythonObject -- floor
    division of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject //= Thing -- augmented floor
    division of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:582:0.

PythonObject % PythonObject -- the modulo operator for Python objects
*********************************************************************

  * Operator: % (Macaulay2Doc),
  * Usage:
        x % y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the remainder when x is divided
        by y;

Description
===========

Perform the modulo operator on Python objects.

+------------------------------+
|i1 : toPython 5 % toPython 3  |
|                              |
|o1 = 2                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+------------------------------+
|i2 : toPython 9 % 5           |
|                              |
|o2 = 4                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 11 % toPython 7          |
|                              |
|o3 = 4                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

Note that the behavior of the modulo operator for integers differs between
Macaulay2 and Python.  In particular, in Macaulay2, the remainder is always
nonnegative. In Python, the remainder will have the same sign as y.

+------------------------------+
|i4 : 5 % -3                   |
|                              |
|o4 = 2                        |
+------------------------------+
|i5 : toPython 5 % -3          |
|                              |
|o5 = -1                       |
|                              |
|o5 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject // PythonObject -- floor
    division of Python objects
  * quotientRemainder(PythonObject,PythonObject)
    -- get the quotient and
    remainder when dividing Python objects
  * PythonObject %= Thing -- augmented modulo
    operator for Python objects

Ways to use this method:
========================

  * PythonObject % PythonObject -- the
    modulo operator for Python objects
  * "PythonObject % Thing"
  * "Thing % PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:623:0.

PythonObject %= Thing -- augmented modulo operator for Python objects
*********************************************************************

  * Operator: %= (Macaulay2Doc),
  * Usage:
        x %= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, the remainder when x is divided
        by y, assigned to x;

Description
===========

Divide two Python objects, giving the remainder, and assign the result to the
first argument.

+------------------------------+
|i1 : x = toPython 5           |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x %= toPython 3          |
|                              |
|o2 = 2                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 2                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+------------------------------+
|i4 : x = toPython 12          |
|                              |
|o4 = 12                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x %= 5                   |
|                              |
|o5 = 2                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 2                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __imod__ method for in-place modulo, then
it will be called.  Otherwise, x and y will be divided in the usual way,
creating a new Python object that is assigned back to x.

For example, NumPy arrays support in-place modulo.  In the example below, x is
modified  directly, and no new object is created.

+------------------------------------------+
|i7 : installNumPyMethods();               |
+------------------------------------------+
|i8 : x = toPython matrix {{7, 8}, {9, 10}}|
|                                          |
|o8 = [[ 7  8]                             |
|      [ 9 10]]                            |
|                                          |
|o8 : PythonObject of class numpy.ndarray  |
+------------------------------------------+
|i9 : x %= matrix {{3, 4}, {5, 6}}         |
|                                          |
|o9 = [[1 0]                               |
|      [4 4]]                              |
|                                          |
|o9 : PythonObject of class numpy.ndarray  |
+------------------------------------------+
|i10 : x                                   |
|                                          |
|o10 = [[1 0]                              |
|       [4 4]]                             |
|                                          |
|o10 : PythonObject of class numpy.ndarray |
+------------------------------------------+

See also
========

  * PythonObject % PythonObject -- the
    modulo operator for Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject %= Thing -- augmented modulo
    operator for Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:687:0.

quotientRemainder(PythonObject,PythonObject) -- get the quotient and remainder when dividing Python objects
***********************************************************************************************************

  * Function: quotientRemainder (Macaulay2Doc),
  * Usage:
        quotientRemainder(x, y)
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a sequence (Macaulay2Doc), containing two Python
        objects;

Description
===========

This returns a sequence containing both the quotient and remainder when
dividing the first argument by the second.  Note that the return value is a
Macaulay2 sequence and not a Python tuple.  This makes it useful with parallel
assignment.

+-------------------------------------------------------+
|i1 : (q, r) = quotientRemainder(toPython 5, toPython 3)|
|                                                       |
|o1 = (1, 2)                                            |
|                                                       |
|o1 : Sequence                                          |
+-------------------------------------------------------+
|i2 : q                                                 |
|                                                       |
|o2 = 1                                                 |
|                                                       |
|o2 : PythonObject of class int                         |
+-------------------------------------------------------+
|i3 : r                                                 |
|                                                       |
|o3 = 2                                                 |
|                                                       |
|o3 : PythonObject of class int                         |
+-------------------------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before dividing.

+--------------------------------------+
|i4 : quotientRemainder(toPython 9, 5) |
|                                      |
|o4 = (1, 4)                           |
|                                      |
|o4 : Sequence                         |
+--------------------------------------+
|i5 : quotientRemainder(11, toPython 7)|
|                                      |
|o5 = (1, 4)                           |
|                                      |
|o5 : Sequence                         |
+--------------------------------------+

Note that the behavior of this function for integers differs between Macaulay2
and Python.  In particular, in Macaulay2, the quotient is rounded down when y
is positive and up when it is negative, and the remainder is always
nonnegative. In Python, the quotient is always rounded down and the remainder
will have the same sign as y.

+--------------------------------------+
|i6 : quotientRemainder(5, -3)         |
|                                      |
|o6 = (-1, 2)                          |
|                                      |
|o6 : Sequence                         |
+--------------------------------------+
|i7 : quotientRemainder(toPython 5, -3)|
|                                      |
|o7 = (-2, -1)                         |
|                                      |
|o7 : Sequence                         |
+--------------------------------------+

See also
========

  * PythonObject // PythonObject -- floor
    division of Python objects
  * PythonObject % PythonObject -- the
    modulo operator for Python objects

Ways to use this method:
========================

  * quotientRemainder(PythonObject,PythonObject)
    -- get the quotient and
    remainder when dividing Python objects
  * "quotientRemainder(PythonObject,Thing)"
  * "quotientRemainder(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:731:0.

PythonObject ^ PythonObject -- exponentiation of Python objects
***************************************************************

  * Operator: ^ (Macaulay2Doc),
  * Usage:
        x ^ y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, x raised to the y power;

Description
===========

Raise one Python object to the power of another.

+------------------------------+
|i1 : (toPython 2)^(toPython 3)|
|                              |
|o1 = 8                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

In addition to the Macaulay2-style ^, this operation is also available using
the Python-style **.

+------------------------------+
|i2 : toPython 2 ** toPython 3 |
|                              |
|o2 = 8                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

Note that parentheses were not necessary in the latter case since ** has much
lower precedence than ^.

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before exponentiating.

+------------------------------+
|i3 : (toPython 2)^3           |
|                              |
|o3 = 8                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+
|i4 : 4^(toPython 5)           |
|                              |
|o4 = 1024                     |
|                              |
|o4 : PythonObject of class int|
+------------------------------+

Caveat
======

In Python, the ^ operator corresponds to the bitwise xor operation. We use ^^
in this case for consistency with the rest of Macaulay2.

See also
========

  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * PythonObject ^= Thing -- augmented
    exponentiation for Python objects

Ways to use this method:
========================

  * PythonObject ^ PythonObject, --
    exponentiation of Python objects
  * "PythonObject ^ Thing"
  * "Thing ^ PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:777:0.

PythonObject ^= Thing -- augmented exponentiation for Python objects
********************************************************************

  * Operator: ^= (Macaulay2Doc),
  * Usage:
        x ^= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, x raised to the y power, assigned
        to x;

Description
===========

Raise one Python object to the power of another, and assign the result to the
first argument.

+------------------------------+
|i1 : x = toPython 2           |
|                              |
|o1 = 2                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x ^= toPython 3          |
|                              |
|o2 = 8                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 8                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

In addition to the Macaulay2-style ^=, this operation is also available using
the Python-style **=.

+------------------------------+
|i4 : x = toPython 6           |
|                              |
|o4 = 6                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x **= toPython 2         |
|                              |
|o5 = 36                       |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 36                       |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before exponentiating.

+------------------------------+
|i7 : x = toPython 16          |
|                              |
|o7 = 16                       |
|                              |
|o7 : PythonObject of class int|
+------------------------------+
|i8 : x ^= 2                   |
|                              |
|o8 = 256                      |
|                              |
|o8 : PythonObject of class int|
+------------------------------+
|i9 : x                        |
|                              |
|o9 = 256                      |
|                              |
|o9 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __ipow__ method for in-place
exponentiation, then it will be called.  Otherwise, x will be raised to the y
power in the usual way, creating a new Python object that is assigned back to
x.

For example, NumPy arrays support in-place exponentiation.  In the example
below, x is modified  directly, and no new object is created.

+-----------------------------------------+
|i7 : installNumPyMethods();              |
+-----------------------------------------+
|i8 : x = toPython matrix {{1, 2}, {3, 4}}|
|                                         |
|o8 =  [[1 2]                             |
|       [3 4]]                            |
|                                         |
|o8 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i9 : x ^= 2                              |
|                                         |
|o9 = [[ 1  4]                            |
|      [ 9 16]]                           |
|                                         |
|o9 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i10 : x                                  |
|                                         |
|o10 = [[ 1  4]                           |
|       [ 9 16]]                          |
|                                         |
|o10 : PythonObject of class numpy.ndarray|
+-----------------------------------------+

See also
========

  * PythonObject ^ PythonObject, --
    exponentiation of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject ^= Thing -- augmented
    exponentiation for Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/arithmetic.m2:849:0.

abs(PythonObject) -- absolute value of a python object
******************************************************

  * Function: abs (Macaulay2Doc),
  * Usage:
        abs x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the absolute value of x;

Description
===========

This is equivalent to the Python abs (see
https://docs.python.org/3/library/functions.html#abs ) function.

+------------------------------+
|i1 : abs toPython(-12)        |
|                              |
|o1 = 12                       |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * abs(PythonObject) -- absolute value of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:378:0.

PythonObject << PythonObject -- the left shift operator for Python objects
**************************************************************************

  * Operator: << (Macaulay2Doc),
  * Usage:
        x << y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the result of shifting x left by
        y;

Description
===========

Perform the left shift operator on Python objects.

+------------------------------+
|i1 : toPython 1 << toPython 3 |
|                              |
|o1 = 8                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before shifting.

+------------------------------+
|i2 : toPython 1 << 4          |
|                              |
|o2 = 16                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 1 << toPython 5          |
|                              |
|o3 = 32                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject >> PythonObject -- the
    right shift operator for Python objects
  * PythonObject <<= Thing -- augmented left
    shift for Python objects

Ways to use this method:
========================

  * PythonObject << PythonObject -- the
    left shift operator for Python objects
  * "PythonObject << Thing"
  * "Thing << PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:36:0.

PythonObject <<= Thing -- augmented left shift for Python objects
*****************************************************************

  * Operator: <<= (Macaulay2Doc),
  * Usage:
        x <<= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, x shifted left by y, assigned to
        x;

Description
===========

Perform the left shift operator on Python objects, and assign the result to the
first argument.

+------------------------------+
|i1 : x = toPython 1           |
|                              |
|o1 = 1                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x <<= toPython 3         |
|                              |
|o2 = 8                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 8                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before shifting.

+------------------------------+
|i4 : x = toPython 1           |
|                              |
|o4 = 1                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x <<= 5                  |
|                              |
|o5 = 32                       |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 32                       |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __ilshift__ method for in-place left shift,
then it will be called.  Otherwise, x will be shifted by y in the usual way,
creating a new Python object that is assigned back to x.

For example, NumPy arrays support in-place left shift.  In the example below, x
is modified  directly, and no new object is created.

+-----------------------------------------+
|i7 : installNumPyMethods();              |
+-----------------------------------------+
|i8 : x = toPython matrix {{1, 2}, {4, 8}}|
|                                         |
|o8 =  [[1 2]                             |
|       [4 8]]                            |
|                                         |
|o8 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i9 : x <<= 2                             |
|                                         |
|o9 = [[ 4  8]                            |
|      [16 32]]                           |
|                                         |
|o9 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i10 : x                                  |
|                                         |
|o10 = [[ 4  8]                           |
|       [16 32]]                          |
|                                         |
|o10 : PythonObject of class numpy.ndarray|
+-----------------------------------------+

See also
========

  * PythonObject << PythonObject -- the
    left shift operator for Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject <<= Thing -- augmented left
    shift for Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:100:0.

PythonObject >> PythonObject -- the right shift operator for Python objects
***************************************************************************

  * Operator: >> (Macaulay2Doc),
  * Usage:
        x >> y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the result of shifting x right by
        y;

Description
===========

Perform the right shift operator on Python objects.

+-------------------------------+
|i1 : toPython 128 >> toPython 3|
|                               |
|o1 = 16                        |
|                               |
|o1 : PythonObject of class int |
+-------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before shifting.

+------------------------------+
|i2 : toPython 256 >> 5        |
|                              |
|o2 = 8                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 16384 >> toPython 4      |
|                              |
|o3 = 1024                     |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject << PythonObject -- the
    left shift operator for Python objects
  * PythonObject >>= Thing -- augmented right
    shift for Python objects

Ways to use this method:
========================

  * PythonObject >> PythonObject -- the
    right shift operator for Python objects
  * "PythonObject >> Thing"
  * "Thing >> PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:132:0.

PythonObject >>= Thing -- augmented right shift for Python objects
******************************************************************

  * Operator: >>= (Macaulay2Doc),
  * Usage:
        x >>= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, x shifted right by y, assigned to
        x;

Description
===========

Perform the right shift operator on Python objects, and assign the result to
the first argument.

+------------------------------+
|i1 : x = toPython 8           |
|                              |
|o1 = 8                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x >>= toPython 3         |
|                              |
|o2 = 1                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 1                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object before shifting.

+------------------------------+
|i4 : x = toPython 32          |
|                              |
|o4 = 32                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x >>= 5                  |
|                              |
|o5 = 1                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 1                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __irshift__ method for in-place right
shift, then it will be called.  Otherwise, x will be shifted by y in the usual
way, creating a new Python object that is assigned back to x.

For example, NumPy arrays support in-place right shift.  In the example below,
x is modified  directly, and no new object is created.

+-------------------------------------------+
|i7 : installNumPyMethods();                |
+-------------------------------------------+
|i8 : x = toPython matrix {{4, 8}, {16, 32}}|
|                                           |
|o8 =  [[ 4  8]                             |
|       [16 32]]                            |
|                                           |
|o8 : PythonObject of class numpy.ndarray   |
+-------------------------------------------+
|i9 : x >>= 2                               |
|                                           |
|o9 = [[1 2]                                |
|      [4 8]]                               |
|                                           |
|o9 : PythonObject of class numpy.ndarray   |
+-------------------------------------------+
|i10 : x                                    |
|                                           |
|o10 = [[1 2]                               |
|       [4 8]]                              |
|                                           |
|o10 : PythonObject of class numpy.ndarray  |
+-------------------------------------------+

See also
========

  * PythonObject >> PythonObject -- the
    right shift operator for Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject >>= Thing -- augmented right
    shift for Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:196:0.

PythonObject & PythonObject -- bitwise conjunction of Python objects
********************************************************************

  * Operator: & (Macaulay2Doc),
  * Usage:
        x & y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, bitwise conjunction of x and y;

Description
===========

Perform the bitwise conjunction ("and") operation on Python objects.

+------------------------------+
|i1 : toPython 6 & toPython 3  |
|                              |
|o1 = 2                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i2 : toPython 14 & 7          |
|                              |
|o2 = 6                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 14 & toPython 7          |
|                              |
|o3 = 6                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject | PythonObject -- bitwise
    disjunction of Python objects
  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * PythonObject ~ -- bitwise negation of a python
    object
  * PythonObject and PythonObject, --
    logical conjunction of Python objects
  * PythonObject &= Thing -- augmented bitwise
    conjunction of Python objects

Ways to use this method:
========================

  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects
  * "PythonObject & Thing"
  * "Thing & PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:231:0.

PythonObject &= Thing -- augmented bitwise conjunction of Python objects
************************************************************************

  * Operator: &= (Macaulay2Doc),
  * Usage:
        x &= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, bitwise conjunction of x and y,
        assigned to x;

Description
===========

Perform the bitwise conjunction ("and") operation on Python objects, and assign
the result to the first argument.

+------------------------------+
|i1 : x = toPython 6           |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x &= toPython 3          |
|                              |
|o2 = 2                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 2                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i4 : x = toPython 14          |
|                              |
|o4 = 14                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x &= 7                   |
|                              |
|o5 = 6                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 6                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __iand__ method for in-place and, then it
will be called.  Otherwise, x will and'ed with y in the usual way, creating a
new Python object that is assigned back to x.

For example, NumPy arrays support in-place and.  In the example below, x is
modified  directly, and no new object is created.

+-----------------------------------------+
|i7 : installNumPyMethods();              |
+-----------------------------------------+
|i8 : x = toPython matrix {{1, 2}, {3, 4}}|
|                                         |
|o8 = [[1 2]                              |
|      [3 4]]                             |
|                                         |
|o8 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i9 : x &= 2                              |
|                                         |
|o9 = [[0 2]                              |
|      [2 0]]                             |
|                                         |
|o9 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i10 : x                                  |
|                                         |
|o10 = [[0 2]                             |
|       [2 0]]                            |
|                                         |
|o10 : PythonObject of class numpy.ndarray|
+-----------------------------------------+

See also
========

  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject &= Thing -- augmented bitwise
    conjunction of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:295:0.

PythonObject | PythonObject -- bitwise disjunction of Python objects
********************************************************************

  * Operator: | (Macaulay2Doc),
  * Usage:
        x | y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, bitwise disjunction of x and y;

Description
===========

Perform the bitwise disjunction ("or") operation on Python objects.

+------------------------------+
|i1 : toPython 6 or toPython 3 |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i2 : toPython 14 | 7          |
|                              |
|o2 = 15                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 14 | toPython 7          |
|                              |
|o3 = 15                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects
  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * PythonObject ~ -- bitwise negation of a python
    object
  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * PythonObject |= Thing -- augmented bitwise
    disjunction of Python objects

Ways to use this method:
========================

  * PythonObject | PythonObject -- bitwise
    disjunction of Python objects
  * "PythonObject | Thing"
  * "Thing | PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:330:0.

PythonObject |= Thing -- augmented bitwise disjunction of Python objects
************************************************************************

  * Operator: |= (Macaulay2Doc),
  * Usage:
        x |= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, bitwise disjunction of x and y,
        assigned to x;

Description
===========

Perform the bitwise disjunction ("or") operation on Python objects, and assign
the result to the first argument.

+------------------------------+
|i1 : x = toPython 6           |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x |= toPython 3          |
|                              |
|o2 = 7                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 7                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i4 : x = toPython 14          |
|                              |
|o4 = 14                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x |= 7                   |
|                              |
|o5 = 15                       |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 15                       |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __ior__ method for in-place or, then it
will be called.  Otherwise, x will or'ed with y in the usual way, creating a
new Python object that is assigned back to x.

For example, NumPy arrays support in-place or.  In the example below, x is
modified  directly, and no new object is created.

+-----------------------------------------+
|i7 : installNumPyMethods();              |
+-----------------------------------------+
|i8 : x = toPython matrix {{1, 2}, {3, 4}}|
|                                         |
|o8 = [[1 2]                              |
|      [3 4]]                             |
|                                         |
|o8 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i9 : x |= 2                              |
|                                         |
|o9 = [[3 2]                              |
|      [3 6]]                             |
|                                         |
|o9 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i10 : x                                  |
|                                         |
|o10 = [[3 2]                             |
|       [3 6]]                            |
|                                         |
|o10 : PythonObject of class numpy.ndarray|
+-----------------------------------------+

See also
========

  * PythonObject | PythonObject -- bitwise
    disjunction of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject |= Thing -- augmented bitwise
    disjunction of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:394:0.

PythonObject ^^ PythonObject -- bitwise exclusive disjunction of Python objects
*******************************************************************************

  * Operator: ^^ (Macaulay2Doc),
  * Usage:
        x ^^ y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, bitwise exclusive disjunction of
        x and y;

Description
===========

Perform the bitwise exclusive disjunction ("xor") operation on Python objects.

+------------------------------+
|i1 : toPython 6 ^^ toPython 3 |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i2 : toPython 14 ^^ 7         |
|                              |
|o2 = 9                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : 14 ^^ toPython 7         |
|                              |
|o3 = 9                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

Caveat
======

In Python, the ^ operator corresponds to the bitwise xor operation. We use ^^
in this case for consistency with the rest of Macaulay2. The ^ operator is used
for exponentiation.

See also
========

  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects
  * PythonObject | PythonObject -- bitwise
    disjunction of Python objects
  * PythonObject ~ -- bitwise negation of a python
    object
  * PythonObject xor PythonObject, --
    logical exclusive disjunction of Python objects
  * PythonObject ^ PythonObject, --
    exponentiation of Python objects
  * PythonObject ^^= Thing -- augmented bitwise
    exclusive disjunction of Python objects

Ways to use this method:
========================

  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * "PythonObject ^^ Thing"
  * "Thing ^^ PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:435:0.

PythonObject ^^= Thing -- augmented bitwise exclusive disjunction of Python objects
***********************************************************************************

  * Operator: ^^= (Macaulay2Doc),
  * Usage:
        x ^^= y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object, bitwise exclusive disjunction of
        x and y, assigned to x;

Description
===========

Perform the bitwise exclusive disjunction ("xor") operation on Python objects,
and assign the result to the first argument.

+------------------------------+
|i1 : x = toPython 6           |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : x ^^= toPython 3         |
|                              |
|o2 = 5                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 5                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

If the right-hand side is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i4 : x = toPython 14          |
|                              |
|o4 = 14                       |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : x ^^= 7                  |
|                              |
|o5 = 9                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+
|i6 : x                        |
|                              |
|o6 = 9                        |
|                              |
|o6 : PythonObject of class int|
+------------------------------+

If the Python class of x defines an __ixor__ method for in-place xor, then it
will be called.  Otherwise, x will xor'ed with y in the usual way, creating a
new Python object that is assigned back to x.

For example, NumPy arrays support in-place xor.  In the example below, x is
modified  directly, and no new object is created.

+-----------------------------------------+
|i7 : installNumPyMethods();              |
+-----------------------------------------+
|i8 : x = toPython matrix {{1, 2}, {3, 4}}|
|                                         |
|o8 = [[1 2]                              |
|      [3 4]]                             |
|                                         |
|o8 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i9 : x ^^= 2                             |
|                                         |
|o9 = [[3 0]                              |
|      [1 6]]                             |
|                                         |
|o9 : PythonObject of class numpy.ndarray |
+-----------------------------------------+
|i10 : x                                  |
|                                         |
|o10 = [[3 0]                             |
|       [1 6]]                            |
|                                         |
|o10 : PythonObject of class numpy.ndarray|
+-----------------------------------------+

See also
========

  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * augmented assignment (Macaulay2Doc)
  * installNumPyMethods -- install NumPy methods

Ways to use this method:
========================

  * PythonObject ^^= Thing -- augmented bitwise
    exclusive disjunction of Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:499:0.

PythonObject ~ -- bitwise negation of a python object
*****************************************************

  * Operator: ~ (Macaulay2Doc),
  * Usage:
        x~
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the bitwise negation of x;

Description
===========

This operation negates each bit.  For integers, this is equivalent to CODE "-x
- 1".  Unlike Python, ~ is a postfix unary operator in Macaulay2.

+------------------------------+
|i1 : (toPython 5)~            |
|                              |
|o1 = -6                       |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects
  * PythonObject | PythonObject -- bitwise
    disjunction of Python objects
  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects
  * not PythonObject -- logical negation of a python
    object

Ways to use this method:
========================

  * PythonObject ~ -- bitwise negation of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/bitwise.m2:524:0.

PythonObject and PythonObject -- logical conjunction of Python objects
**********************************************************************

  * Operator: and (Macaulay2Doc),
  * Usage:
        x and y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, logical conjunction of x and y;

Description
===========

Perform the logical conjunction ("and") operation on Python objects.

+------------------------------------+
|i1 : toPython true and toPython true|
|                                    |
|o1 = True                           |
|                                    |
|o1 : PythonObject of class bool     |
+------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+----------------------------+
|i2 : toPython true and false|
|                            |
|o2 = false                  |
+----------------------------+
|i3 : false and toPython true|
|                            |
|o3 = false                  |
+----------------------------+

Unlike Macaulay2, Python supports using and with non-boolean objects.  In this
case, the first argument is returned if it is "falsy". Otherwise, the second
argument is returned.

+----------------------------------+
|i4 : toPython 0 and toPython "foo"|
|                                  |
|o4 = 0                            |
|                                  |
|o4 : PythonObject of class int    |
+----------------------------------+
|i5 : toPython 5 and toPython "bar"|
|                                  |
|o5 = bar                          |
|                                  |
|o5 : PythonObject of class str    |
+----------------------------------+

In Python, when the first argument is falsy, then is is returned immediately
without evaluating the second argument.  This is known as "short-circuiting".
However, in Macaulay2, both arguments are evaluated before the Python
conjunction method is called.

+---------------------------------------+
|i6 : stopIfError = false               |
|                                       |
|o6 = false                             |
+---------------------------------------+
|i7 : toPython 0 and 1/0                |
|stdio:7:16:(3): error: division by zero|
+---------------------------------------+

However, if the first argument is the Macaulay2 false (Macaulay2Doc),
object, then short-cicuiting will occur.

+--------------------------------+
|i8 : false and pythonValue "1/0"|
|                                |
|o8 = false                      |
+--------------------------------+

See also
========

  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * PythonObject xor PythonObject, --
    logical exclusive disjunction of Python objects
  * not PythonObject -- logical negation of a python
    object
  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects

Ways to use this method:
========================

  * PythonObject and PythonObject, --
    logical conjunction of Python objects
  * "PythonObject and Thing"
  * "Thing and PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/logical.m2:56:0.

PythonObject or PythonObject -- logical disjunction of Python objects
*********************************************************************

  * Operator: or (Macaulay2Doc),
  * Usage:
        x or y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, logical disjunction of x and y;

Description
===========

Perform the logical disjunction ("or") operation on Python objects.

+-----------------------------------+
|i1 : toPython true or toPython true|
|                                   |
|o1 = True                          |
|                                   |
|o1 : PythonObject of class bool    |
+-----------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+-------------------------------+
|i2 : toPython true or false    |
|                               |
|o2 = True                      |
|                               |
|o2 : PythonObject of class bool|
+-------------------------------+
|i3 : false or toPython true    |
|                               |
|o3 = True                      |
|                               |
|o3 : PythonObject of class bool|
+-------------------------------+

Unlike Macaulay2, Python supports using or with non-boolean objects.  In this
case, the first argument is returned if it is "truthy". Otherwise, the second
argument is returned.

+---------------------------------+
|i4 : toPython 0 or toPython "foo"|
|                                 |
|o4 = foo                         |
|                                 |
|o4 : PythonObject of class str   |
+---------------------------------+
|i5 : toPython 5 or toPython "bar"|
|                                 |
|o5 = 5                           |
|                                 |
|o5 : PythonObject of class int   |
+---------------------------------+

In Python, when the first argument is truthy, then is is returned immediately
without evaluating the second argument.  This is known as "short-circuiting".
However, in Macaulay2, both arguments are evaluated before the Python
disjunction method is called.

+---------------------------------------+
|i6 : stopIfError = false               |
|                                       |
|o6 = false                             |
+---------------------------------------+
|i7 : toPython 1 or 1/0                 |
|stdio:7:15:(3): error: division by zero|
+---------------------------------------+

However, if the first argument is the Macaulay2 true (Macaulay2Doc),
object, then short-cicuiting will occur.

+------------------------------+
|i8 : true or pythonValue "1/0"|
|                              |
|o8 = true                     |
+------------------------------+

See also
========

  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * PythonObject xor PythonObject, --
    logical exclusive disjunction of Python objects
  * not PythonObject -- logical negation of a python
    object
  * PythonObject & PythonObject -- bitwise
    conjunction of Python objects

Ways to use this method:
========================

  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * "PythonObject or Thing"
  * "Thing or PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/logical.m2:108:0.

PythonObject xor PythonObject -- logical exclusive disjunction of Python objects
********************************************************************************

  * Operator: xor (Macaulay2Doc),
  * Usage:
        x xor y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, logical exclusive disjunction of
        x and y;

Description
===========

Perform the logical exclusive disjunction ("xor") operation on Python objects.

+------------------------------------+
|i1 : toPython true xor toPython true|
|                                    |
|o1 = False                          |
|                                    |
|o1 : PythonObject of class bool     |
+------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+-------------------------------+
|i2 : toPython true xor false   |
|                               |
|o2 = True                      |
|                               |
|o2 : PythonObject of class bool|
+-------------------------------+
|i3 : false xor toPython true   |
|                               |
|o3 = True                      |
|                               |
|o3 : PythonObject of class bool|
+-------------------------------+

Unlike Macaulay2, Python supports using xor with non-boolean objects. If
exactly one of the arguments is truthy, then it will return that argument.
Otherwise, it will return False.

+----------------------------------+
|i4 : toPython 0 xor toPython "foo"|
|                                  |
|o4 = foo                          |
|                                  |
|o4 : PythonObject of class str    |
+----------------------------------+
|i5 : toPython 5 xor toPython ""   |
|                                  |
|o5 = 5                            |
|                                  |
|o5 : PythonObject of class int    |
+----------------------------------+
|i6 : toPython 6 xor toPython "bar"|
|                                  |
|o6 = False                        |
|                                  |
|o6 : PythonObject of class bool   |
+----------------------------------+

See also
========

  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * PythonObject and PythonObject, --
    logical conjunction of Python objects
  * not PythonObject -- logical negation of a python
    object
  * PythonObject ^^ PythonObject, --
    bitwise exclusive disjunction of Python objects

Ways to use this method:
========================

  * PythonObject xor PythonObject, --
    logical exclusive disjunction of Python objects
  * "PythonObject xor Thing"
  * "Thing xor PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/logical.m2:149:0.

not PythonObject -- logical negation of a python object
*******************************************************

  * Operator: not (Macaulay2Doc),
  * Usage:
        not x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the logical negation of x;

Description
===========

Perform the logical negation ("not") operation on a Python object.

+-------------------------------+
|i1 : not toPython true         |
|                               |
|o1 = False                     |
|                               |
|o1 : PythonObject of class bool|
+-------------------------------+
|i2 : not toPython false        |
|                               |
|o2 = True                      |
|                               |
|o2 : PythonObject of class bool|
+-------------------------------+

Unlike Macaulay2, Python supports using not with non-boolean objects. It will
return False if the argument is truthy and True if it is falsy.

+-------------------------------+
|i3 : not toPython 0            |
|                               |
|o3 = True                      |
|                               |
|o3 : PythonObject of class bool|
+-------------------------------+
|i4 : not toPython "foo"        |
|                               |
|o4 = False                     |
|                               |
|o4 : PythonObject of class bool|
+-------------------------------+

See also
========

  * PythonObject or PythonObject, --
    logical disjunction of Python objects
  * PythonObject and PythonObject, --
    logical conjunction of Python objects
  * PythonObject xor PythonObject, --
    logical exclusive disjunction of Python objects
  * PythonObject ~ -- bitwise negation of a python
    object

Ways to use this method:
========================

  * not PythonObject -- logical negation of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/logical.m2:180:0.

PythonObject ? PythonObject -- compare Python objects
*****************************************************

  * Operator: ? (Macaulay2Doc),
  * Usage:
        x ? y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

Description
===========

Compare two Python objects.  The result is one of the following symbols:
< (Macaulay2Doc), > (Macaulay2Doc), == (Macaulay2Doc), or
incomparable (Macaulay2Doc).

+----------------------------+
|i1 : toPython 2 ? toPython 3|
|                            |
|o1 = <                      |
|                            |
|o1 : Keyword                |
+----------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before comparing.

+-------------------+
|i2 : toPython 4 ? 4|
|                   |
|o2 = ==            |
|                   |
|o2 : Keyword       |
+-------------------+
|i3 : 7 ? toPython 6|
|                   |
|o3 = >             |
|                   |
|o3 : Keyword       |
+-------------------+

This method is used by the comparison operators < (Macaulay2Doc),
> (Macaulay2Doc), <= (Macaulay2Doc), and >= (Macaulay2Doc).

+----------------------------+
|i4 : toPython 2 < toPython 3|
|                            |
|o4 = true                   |
+----------------------------+
|i5 : 4 >= toPython 5        |
|                            |
|o5 = false                  |
+----------------------------+

See also
========

  * PythonObject == PythonObject, --
    equality of Python objects

Ways to use this method:
========================

  * PythonObject ? PythonObject -- compare
    Python objects
  * "PythonObject ? Thing"
  * "Thing ? PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/comparison.m2:38:0.

PythonObject == PythonObject -- equality of Python objects
**********************************************************

  * Operator: == (Macaulay2Doc),
  * Usage:
        x == y
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether x and y are
        equal;

Description
===========

Determine whether two Python objects are equal.

+-----------------------------+
|i1 : toPython 2 == toPython 3|
|                             |
|o1 = false                   |
+-----------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before comparing.

+--------------------+
|i2 : toPython 4 == 4|
|                    |
|o2 = true           |
+--------------------+
|i3 : 7 == toPython 6|
|                    |
|o3 = false          |
+--------------------+

See also
========

  * PythonObject ? PythonObject -- compare
    Python objects

Ways to use this method:
========================

  * PythonObject == PythonObject, --
    equality of Python objects
  * "PythonObject == Thing"
  * "Thing == PythonObject"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/comparison.m2:67:0.

?? PythonObject -- null coalescing operator for Python objects
**************************************************************

  * Operator: ?? (Macaulay2Doc),
  * Usage:
        ?? x
        x ?? y
  * Inputs:
      * x, a python object,

Description
===========

When the first argument to the binary null coalescing operator is a Python
object, it will be returned unless that object is None, in which case the
second argument is returned.

+-----------------------------------+
|i1 : toPython 3 ?? 4               |
|                                   |
|o1 = 3                             |
|                                   |
|o1 : PythonObject of class int     |
+-----------------------------------+
|i2 : toPython null                 |
|                                   |
|o2 = None                          |
|                                   |
|o2 : PythonObject of class NoneType|
+-----------------------------------+
|i3 : oo ?? 5                       |
|                                   |
|o3 = 5                             |
+-----------------------------------+

For the unary version, the argument itself is returned unless it is None, in
which case null (Macaulay2Doc), is returned.

+------------------------------+
|i4 : ?? toPython 6            |
|                              |
|o4 = 6                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : ?? toPython null         |
+------------------------------+

Ways to use this method:
========================

  * ?? PythonObject -- null coalescing operator for
    Python objects
-------------------------------------------------------------------------------

The source of this document is in Python/doc/comparison.m2:94:0.

binomial(PythonObject,PythonObject) -- binomial coefficient for Python objects
******************************************************************************

  * Function: binomial (Macaulay2Doc),
  * Usage:
        binomial(n, k)
  * Inputs:
      * n, a python object,
      * k, a python object,
  * Outputs:
      * an integer (Macaulay2Doc),

Description
===========

This computes the number of k-element subsets of a set with n elements.

+-------------------------------------+
|i1 : binomial(toPython 4, toPython 2)|
|                                     |
|o1 = 6                               |
|                                     |
|o1 : PythonObject of class int       |
+-------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i2 : binomial(toPython 12, 3) |
|                              |
|o2 = 220                      |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : binomial(15, toPython 10)|
|                              |
|o3 = 3003                     |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

See also
========

  * PythonObject ! -- factorial of a Python object

Ways to use this method:
========================

  * binomial(PythonObject,PythonObject)
    -- binomial coefficient for
    Python objects
  * "binomial(PythonObject,Thing)"
  * "binomial(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/number-theory.m2:32:0.

PythonObject ! -- factorial of a Python object
**********************************************

  * Operator: ! (Macaulay2Doc),
  * Usage:
        x!
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the factorial of x;

Description
===========

This computes the factorial of a Python object.

+------------------------------+
|i1 : (toPython 5)!            |
|                              |
|o1 = 120                      |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

See also
========

  * binomial(PythonObject,PythonObject)
    -- binomial coefficient for
    Python objects

Ways to use this method:
========================

  * PythonObject ! -- factorial of a Python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/number-theory.m2:52:0.

gcd(PythonObject,PythonObject) -- greatest common divisor of Python objects
***************************************************************************

  * Function: gcd (Macaulay2Doc),
  * Usage:
        gcd(x, y)
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the greatest common divisor of x
        and y;

Description
===========

This computes the greatest common divisor of two Python objects.

+----------------------------------+
|i1 : gcd(toPython 12, toPython 15)|
|                                  |
|o1 = 3                            |
|                                  |
|o1 : PythonObject of class int    |
+----------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i2 : gcd(toPython 12, 15)     |
|                              |
|o2 = 3                        |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : gcd(12, toPython 15)     |
|                              |
|o3 = 3                        |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

Since gcd is a binary method, it will accept any number of arguments.

+--------------------------------------+
|i4 : gcd toPython 5                   |
|                                      |
|o4 = 5                                |
|                                      |
|o4 : PythonObject of class int        |
+--------------------------------------+
|i5 : gcd (toPython 7, toPython 14, 28)|
|                                      |
|o5 = 7                                |
|                                      |
|o5 : PythonObject of class int        |
+--------------------------------------+

See also
========

  * lcm(PythonObject,PythonObject),
    -- least common multiple of Python objects

Ways to use this method:
========================

  * "gcd(PythonObject)"
  * gcd(PythonObject,PythonObject),
    -- greatest common divisor of Python objects
  * "gcd(PythonObject,Thing)"
  * "gcd(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/number-theory.m2:88:0.

lcm(PythonObject,PythonObject) -- least common multiple of Python objects
*************************************************************************

  * Function: lcm (Macaulay2Doc),
  * Usage:
        lcm(x, y)
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object, the least common multiple of x
        and y;

Description
===========

This computes the least common multiple of two Python objects.

+----------------------------------+
|i1 : lcm(toPython 12, toPython 15)|
|                                  |
|o1 = 60                           |
|                                  |
|o1 : PythonObject of class int    |
+----------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object.

+------------------------------+
|i2 : lcm(toPython 12, 15)     |
|                              |
|o2 = 60                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+
|i3 : lcm(12, toPython 15)     |
|                              |
|o3 = 60                       |
|                              |
|o3 : PythonObject of class int|
+------------------------------+

Since lcm is a binary method, it will accept any number of arguments.

+--------------------------------------+
|i4 : lcm toPython 5                   |
|                                      |
|o4 = 5                                |
|                                      |
|o4 : PythonObject of class int        |
+--------------------------------------+
|i5 : lcm (toPython 7, toPython 14, 28)|
|                                      |
|o5 = 28                               |
|                                      |
|o5 : PythonObject of class int        |
+--------------------------------------+

See also
========

  * gcd(PythonObject,PythonObject),
    -- greatest common divisor of Python objects

Ways to use this method:
========================

  * "lcm(PythonObject)"
  * lcm(PythonObject,PythonObject),
    -- least common multiple of Python objects
  * "lcm(PythonObject,Thing)"
  * "lcm(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/number-theory.m2:124:0.

ceiling(PythonObject) -- ceiling of a python object
***************************************************

  * Function: ceiling (Macaulay2Doc),
  * Usage:
        ceiling x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.ceil function, which rounds toward positive
infinity.

+------------------------------+
|i1 : ceiling toPython 5.8     |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : ceiling toPython(-5.8)   |
|                              |
|o2 = -5                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

See also
========

  * floor(PythonObject) -- floor of a python
    object
  * truncate(PythonObject) -- truncate a
    python object

Ways to use this method:
========================

  * ceiling(PythonObject) -- ceiling of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:27:0.

floor(PythonObject) -- floor of a python object
***********************************************

  * Function: floor (Macaulay2Doc),
  * Usage:
        floor x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.floor function, which rounds toward negative
infinity.

+------------------------------+
|i1 : floor toPython 5.8       |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : floor toPython(-5.8)     |
|                              |
|o2 = -6                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

See also
========

  * ceiling(PythonObject) -- ceiling of a
    python object
  * truncate(PythonObject) -- truncate a
    python object

Ways to use this method:
========================

  * floor(PythonObject) -- floor of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:50:0.

remainder(PythonObject,PythonObject) -- remainder of python objects
*******************************************************************

  * Function: remainder (Macaulay2Doc),
  * Usage:
        remainder(x, y)
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.remainder function, which computes the IEEE
754-style remainder of x with respect to y.  In particular, this is $x - qy$,
where q is the integer closed to $\frac{x}{y}$, breaking ties by rounding
$\frac{1}{2}$ to the nearest even integer.

+--------------------------------------+
|i1 : remainder(toPython 7, toPython 2)|
|                                      |
|o1 = -1.0                             |
|                                      |
|o1 : PythonObject of class float      |
+--------------------------------------+
|i2 : remainder(toPython 9, toPython 2)|
|                                      |
|o2 = 1.0                              |
|                                      |
|o2 : PythonObject of class float      |
+--------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before computing the remainder.

+--------------------------------+
|i3 : remainder(toPython 7, 2)   |
|                                |
|o3 = -1.0                       |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+
|i4 : remainder(9, toPython 9)   |
|                                |
|o4 = 0.0                        |
|                                |
|o4 : PythonObject of class float|
+--------------------------------+

Ways to use this method:
========================

  * remainder(PythonObject,PythonObject)
    -- remainder of python objects
  * "remainder(PythonObject,Thing)"
  * "remainder(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:82:0.

round(PythonObject,PythonObject) -- round a python object
*********************************************************

  * Function: round (Macaulay2Doc),
  * Usage:
        round(n, x)
        round x
  * Inputs:
      * n, a python object,
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in round function, which round x to n decimal places,
or to the nearest integer if n is not given.

+--------------------------------+
|i1 : x = (import "math")@@pi    |
|                                |
|o1 = 3.141592653589793          |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : round x                    |
|                                |
|o2 = 3                          |
|                                |
|o2 : PythonObject of class int  |
+--------------------------------+
|i3 : round(3, x)                |
|                                |
|o3 = 3.142                      |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+

Ties are broken by round half to even.

+------------------------------+
|i4 : round toPython 2.5       |
|                              |
|o4 = 2                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : round toPython 3.5       |
|                              |
|o5 = 4                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * "round(PythonObject)"
  * round(PythonObject,PythonObject)
    -- round a python object
  * "round(PythonObject,Thing)"
  * "round(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:114:0.

truncate(PythonObject) -- truncate a python object
**************************************************

  * Function: truncate (Macaulay2Doc),
  * Usage:
        truncate x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.trunc function, which rounds toward zero.

+------------------------------+
|i1 : truncate toPython 5.8    |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : truncate toPython(-5.8)  |
|                              |
|o2 = -5                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

See also
========

  * ceiling(PythonObject) -- ceiling of a
    python object
  * floor(PythonObject) -- floor of a python
    object

Ways to use this method:
========================

  * truncate(PythonObject) -- truncate a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:137:0.

isFinite(PythonObject) -- whether a Python object is finite
***********************************************************

  * Function: isFinite (Macaulay2Doc),
  * Usage:
        isFinite x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

Description
===========

Description This function returns true when x is a finite number. Example
isFinite toPython 3 isFinite toPython infinity

See also
========

  * isInfinite(PythonObject) -- whether a
    Python object is infinite

Ways to use this method:
========================

  * isFinite(PythonObject) -- whether a
    Python object is finite
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:159:0.

isInfinite(PythonObject) -- whether a Python object is infinite
***************************************************************

  * Function: isInfinite (Macaulay2Doc),
  * Usage:
        isInfinite x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

Description
===========

This function returns true when x is an infinite number.

+---------------------------------+
|i1 : isInfinite toPython infinity|
|                                 |
|o1 = true                        |
+---------------------------------+
|i2 : isInfinite toPython 3       |
|                                 |
|o2 = false                       |
+---------------------------------+

See also
========

  * isFinite(PythonObject) -- whether a
    Python object is finite

Ways to use this method:
========================

  * isInfinite(PythonObject) -- whether a
    Python object is infinite
-------------------------------------------------------------------------------

The source of this document is in Python/doc/floating-point.m2:180:0.

exp(PythonObject) -- exponential of a python object
***************************************************

  * Function: exp (Macaulay2Doc),
  * Usage:
        exp x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.exp function, which computes the exponential
of x.

+--------------------------------+
|i1 : exp toPython 1             |
|                                |
|o1 = 2.718281828459045          |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : exp toPython 0             |
|                                |
|o2 = 1.0                        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * log(PythonObject) -- logarithm
    of a python object
  * expm1(PythonObject) -- exponential minus
    one of a python object

Ways to use this method:
========================

  * exp(PythonObject) -- exponential of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/exp-log.m2:27:0.

expm1(PythonObject) -- exponential minus one of a python object
***************************************************************

  * Function: expm1 (Macaulay2Doc),
  * Usage:
        expm1 x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.expm1 function, which computes the
exponential of x minus one.  This is more accurate than computing exp x - 1 for
small values of x.

+--------------------------------+
|i1 : exp toPython 1e-10 - 1     |
|                                |
|o1 = 1.000000082740371e-10      |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : expm1 toPython 1e-10       |
|                                |
|o2 = 1.00000000005e-10          |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * exp(PythonObject) -- exponential of a python
    object

Ways to use this method:
========================

  * expm1(PythonObject) -- exponential minus
    one of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/exp-log.m2:50:0.

log(PythonObject,PythonObject) -- logarithm of a python object
**************************************************************

  * Function: log (Macaulay2Doc),
  * Usage:
        log x
        log_base x
  * Inputs:
      * x, a python object,
      * base, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.log function, which computes the logarithm of
x to the given base.  If no base is given, then the natural logarithm is
computed.

+--------------------------------+
|i1 : log toPython exp 1         |
|                                |
|o1 = 1.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : log_(toPython 2) toPython 8|
|                                |
|o2 = 3.0                        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before computing the logarithm.

+--------------------------------+
|i3 : log_10 toPython 100        |
|                                |
|o3 = 2.0                        |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+
|i4 : log_(toPython 3) 27        |
|                                |
|o4 = 3.0                        |
|                                |
|o4 : PythonObject of class float|
+--------------------------------+

See also
========

  * exp(PythonObject) -- exponential of a python
    object
  * log1p(PythonObject) -- logarithm plus one
    of a python object

Ways to use this method:
========================

  * "log(PythonObject)"
  * log(PythonObject,PythonObject),
    -- logarithm of a python object
  * "log(PythonObject,Thing)"
  * "log(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/exp-log.m2:85:0.

log1p(PythonObject) -- logarithm plus one of a python object
************************************************************

  * Function: log1p (Macaulay2Doc),
  * Usage:
        log1p x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.log1p function, which computes the logarithm
of x plus one.  This is more accurate than computing log(x + 1) for small
values of x.

+--------------------------------+
|i1 : log(1 + toPython 1e-10)    |
|                                |
|o1 = 1.000000082690371e-10      |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : log1p toPython 1e-10       |
|                                |
|o2 = 9.999999999500001e-11      |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * log(PythonObject) -- logarithm
    of a python object

Ways to use this method:
========================

  * log1p(PythonObject) -- logarithm plus one
    of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/exp-log.m2:108:0.

sqrt(PythonObject) -- square root of a python object
****************************************************

  * Function: sqrt (Macaulay2Doc),
  * Usage:
        sqrt x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.sqrt function, which computes the square root
of x.

+--------------------------------+
|i1 : sqrt toPython 4            |
|                                |
|o1 = 2.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : sqrt toPython 2            |
|                                |
|o2 = 1.4142135623730951         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

Ways to use this method:
========================

  * sqrt(PythonObject) -- square root of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/exp-log.m2:128:0.

acos(PythonObject) -- arc cosine of a python object
***************************************************

  * Function: acos (Macaulay2Doc),
  * Usage:
        acos x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.acos function, which computes the arc cosine
of x.

+--------------------------------+
|i1 : acos toPython 1            |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : acos toPython 0            |
|                                |
|o2 = 1.5707963267948966         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * cos(PythonObject) -- cosine of a python
    object
  * asin(PythonObject) -- arc sine of a python
    object
  * atan(PythonObject) -- arc tangent of a
    python object

Ways to use this method:
========================

  * acos(PythonObject) -- arc cosine of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:28:0.

asin(PythonObject) -- arc sine of a python object
*************************************************

  * Function: asin (Macaulay2Doc),
  * Usage:
        asin x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.asin function, which computes the arc sine of
x.

+--------------------------------+
|i1 : asin toPython 1            |
|                                |
|o1 = 1.5707963267948966         |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : asin toPython 0            |
|                                |
|o2 = 0.0                        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * sin(PythonObject) -- sine of a python object
  * acos(PythonObject) -- arc cosine of a python
    object
  * atan(PythonObject) -- arc tangent of a
    python object

Ways to use this method:
========================

  * asin(PythonObject) -- arc sine of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:52:0.

atan(PythonObject) -- arc tangent of a python object
****************************************************

  * Function: atan (Macaulay2Doc),
  * Usage:
        atan x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.atan function, which computes the arc tangent
of x.

+--------------------------------+
|i1 : atan toPython 1            |
|                                |
|o1 = 0.7853981633974483         |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : atan toPython 0            |
|                                |
|o2 = 0.0                        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * tan(PythonObject) -- tangent of a python
    object
  * asin(PythonObject) -- arc sine of a python
    object
  * acos(PythonObject) -- arc cosine of a python
    object
  * atan2(PythonObject,PythonObject)
    -- arc tangent of quotient of
    python objects

Ways to use this method:
========================

  * atan(PythonObject) -- arc tangent of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:77:0.

atan2(PythonObject,PythonObject) -- arc tangent of quotient of python objects
*****************************************************************************

  * Function: atan2 (Macaulay2Doc),
  * Usage:
        atan2(y, x)
  * Inputs:
      * y, a python object,
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.atan2 function, which computes the arc
tangent of $frac{y}{x}$ between $-\pi$ and $\pi$.

+--------------------------------------+
|i1 : atan2(toPython 1, toPython 1)    |
|                                      |
|o1 = 0.7853981633974483               |
|                                      |
|o1 : PythonObject of class float      |
+--------------------------------------+
|i2 : atan2(toPython(-1), toPython(-1))|
|                                      |
|o2 = -2.356194490192345               |
|                                      |
|o2 : PythonObject of class float      |
+--------------------------------------+

If one of the arguments is a Macaulay2 object, then it is first converted to a
Python object before computing the arc tangent.

+--------------------------------+
|i3 : atan2(1, toPython 1)       |
|                                |
|o3 = 0.7853981633974483         |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+
|i4 : atan2(toPython 0, 1)       |
|                                |
|o4 = 0.0                        |
|                                |
|o4 : PythonObject of class float|
+--------------------------------+

See also
========

  * tan(PythonObject) -- tangent of a python
    object
  * atan(PythonObject) -- arc tangent of a
    python object

Ways to use this method:
========================

  * atan2(PythonObject,PythonObject)
    -- arc tangent of quotient of
    python objects
  * "atan2(PythonObject,Thing)"
  * "atan2(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:109:0.

cos(PythonObject) -- cosine of a python object
**********************************************

  * Function: cos (Macaulay2Doc),
  * Usage:
        cos x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.cos function, which computes the cosine of x.

+--------------------------------+
|i1 : cos toPython 0             |
|                                |
|o1 = 1.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : cos toPython (pi / 2)      |
|                                |
|o2 = 6.123233995736766e-17      |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * acos(PythonObject) -- arc cosine of a python
    object
  * sin(PythonObject) -- sine of a python object
  * tan(PythonObject) -- tangent of a python
    object

Ways to use this method:
========================

  * cos(PythonObject) -- cosine of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:133:0.

sin(PythonObject) -- sine of a python object
********************************************

  * Function: sin (Macaulay2Doc),
  * Usage:
        sin x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.sin function, which computes the sine of x.

+--------------------------------+
|i1 : sin toPython 0             |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : sin toPython (pi / 2)      |
|                                |
|o2 = 1.0                        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * asin(PythonObject) -- arc sine of a python
    object
  * cos(PythonObject) -- cosine of a python
    object
  * tan(PythonObject) -- tangent of a python
    object

Ways to use this method:
========================

  * sin(PythonObject) -- sine of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:157:0.

tan(PythonObject) -- tangent of a python object
***********************************************

  * Function: tan (Macaulay2Doc),
  * Usage:
        tan x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.tan function, which computes the tangent of
x.

+--------------------------------+
|i1 : tan toPython 0             |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : tan toPython (pi / 4)      |
|                                |
|o2 = 0.9999999999999999         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * atan(PythonObject) -- arc tangent of a
    python object
  * atan2(PythonObject,PythonObject)
    -- arc tangent of quotient of
    python objects
  * sin(PythonObject) -- sine of a python object
  * cos(PythonObject) -- cosine of a python
    object

Ways to use this method:
========================

  * tan(PythonObject) -- tangent of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/trig.m2:182:0.

acosh(PythonObject) -- inverse hyperbolic cosine of a python object
*******************************************************************

  * Function: acosh (Macaulay2Doc),
  * Usage:
        acosh x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.acosh function, which computes the inverse
hyperbolic cosine of x.

+--------------------------------+
|i1 : acosh toPython 1           |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : acosh toPython 2           |
|                                |
|o2 = 1.3169578969248166         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * cosh(PythonObject) -- hyperbolic cosine of a
    python object
  * asinh(PythonObject) -- inverse hyperbolic
    sine of a python object
  * atanh(PythonObject) -- inverse hyperbolic
    tangent of a python object

Ways to use this method:
========================

  * acosh(PythonObject) -- inverse hyperbolic
    cosine of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/hyperbolic.m2:28:0.

asinh(PythonObject) -- inverse hyperbolic sine of a python object
*****************************************************************

  * Function: asinh (Macaulay2Doc),
  * Usage:
        asinh x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.asinh function, which computes the inverse
hyperbolic sine of x.

+--------------------------------+
|i1 : asinh toPython 0           |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : asinh toPython 1           |
|                                |
|o2 = 0.881373587019543          |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * sinh(PythonObject) -- hyperbolic sine of a
    python object
  * acosh(PythonObject) -- inverse hyperbolic
    cosine of a python object
  * atanh(PythonObject) -- inverse hyperbolic
    tangent of a python object

Ways to use this method:
========================

  * asinh(PythonObject) -- inverse hyperbolic
    sine of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/hyperbolic.m2:52:0.

atanh(PythonObject) -- inverse hyperbolic tangent of a python object
********************************************************************

  * Function: atanh (Macaulay2Doc),
  * Usage:
        atanh x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.atanh function, which computes the inverse
hyperbolic tangent of x.

+--------------------------------+
|i1 : atanh toPython 0           |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : atanh toPython 0.5         |
|                                |
|o2 = 0.5493061443340548         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * tanh(PythonObject) -- hyperbolic tangent of
    a python object
  * asinh(PythonObject) -- inverse hyperbolic
    sine of a python object
  * acosh(PythonObject) -- inverse hyperbolic
    cosine of a python object

Ways to use this method:
========================

  * atanh(PythonObject) -- inverse hyperbolic
    tangent of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/hyperbolic.m2:76:0.

cosh(PythonObject) -- hyperbolic cosine of a python object
**********************************************************

  * Function: cosh (Macaulay2Doc),
  * Usage:
        cosh x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.cosh function, which computes the hyperbolic
cosine of x.

+--------------------------------+
|i1 : cosh toPython 0            |
|                                |
|o1 = 1.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : cosh toPython 1            |
|                                |
|o2 = 1.5430806348152437         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * acosh(PythonObject) -- inverse hyperbolic
    cosine of a python object
  * sinh(PythonObject) -- hyperbolic sine of a
    python object
  * tanh(PythonObject) -- hyperbolic tangent of
    a python object

Ways to use this method:
========================

  * cosh(PythonObject) -- hyperbolic cosine of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/hyperbolic.m2:100:0.

sinh(PythonObject) -- hyperbolic sine of a python object
********************************************************

  * Function: sinh (Macaulay2Doc),
  * Usage:
        sinh x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.sinh function, which computes the hyperbolic
sine of x.

+--------------------------------+
|i1 : sinh toPython 0            |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : sinh toPython 1            |
|                                |
|o2 = 1.1752011936438014         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * asinh(PythonObject) -- inverse hyperbolic
    sine of a python object
  * cosh(PythonObject) -- hyperbolic cosine of a
    python object
  * tanh(PythonObject) -- hyperbolic tangent of
    a python object

Ways to use this method:
========================

  * sinh(PythonObject) -- hyperbolic sine of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/hyperbolic.m2:124:0.

tanh(PythonObject) -- hyperbolic tangent of a python object
***********************************************************

  * Function: tanh (Macaulay2Doc),
  * Usage:
        tanh x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.tanh function, which computes the hyperbolic
tangent of x.

+--------------------------------+
|i1 : tanh toPython 0            |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : tanh toPython 1            |
|                                |
|o2 = 0.7615941559557649         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * atanh(PythonObject) -- inverse hyperbolic
    tangent of a python object
  * sinh(PythonObject) -- hyperbolic sine of a
    python object
  * cosh(PythonObject) -- hyperbolic cosine of a
    python object

Ways to use this method:
========================

  * tanh(PythonObject) -- hyperbolic tangent of
    a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/hyperbolic.m2:148:0.

erf(PythonObject) -- error function of a python object
******************************************************

  * Function: erf (Macaulay2Doc),
  * Usage:
        erf x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.erf function, which computes the error
function of x.

+--------------------------------+
|i1 : erf toPython 0             |
|                                |
|o1 = 0.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : erf toPython 1             |
|                                |
|o2 = 0.8427007929497149         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * erfc(PythonObject) -- complementary error
    function of a python object

Ways to use this method:
========================

  * erf(PythonObject) -- error function of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/special.m2:26:0.

erfc(PythonObject) -- complementary error function of a python object
*********************************************************************

  * Function: erfc (Macaulay2Doc),
  * Usage:
        erfc x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.erfc function, which computes the
complementary error function of x, i.e., 1 - erf(x).

+--------------------------------+
|i1 : erfc toPython 0            |
|                                |
|o1 = 1.0                        |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : erfc toPython 1            |
|                                |
|o2 = 0.15729920705028513        |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+
|i3 : 1 - erf toPython 1         |
|                                |
|o3 = 0.1572992070502851         |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+

See also
========

  * erf(PythonObject) -- error function of a
    python object

Ways to use this method:
========================

  * erfc(PythonObject) -- complementary error
    function of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/special.m2:49:0.

Gamma(PythonObject) -- gamma function of a python object
********************************************************

  * Function: Gamma (Macaulay2Doc),
  * Usage:
        Gamma x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.gamma function, which computes the gamma
function of x.

+--------------------------------+
|i1 : Gamma toPython 5           |
|                                |
|o1 = 24.0                       |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : Gamma toPython 0.5         |
|                                |
|o2 = 1.7724538509055159         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * lngamma(PythonObject) -- natural
    logarithm of the gamma function of a python object

Ways to use this method:
========================

  * Gamma(PythonObject) -- gamma function of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/special.m2:71:0.

lngamma(PythonObject) -- natural logarithm of the gamma function of a python object
***********************************************************************************

  * Function: lngamma (Macaulay2Doc),
  * Usage:
        lngamma x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.lgamma function, which computes the natural
logarithm of the gamma function of x.

+--------------------------------+
|i1 : lngamma toPython 5         |
|                                |
|o1 = 3.178053830347945          |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : log Gamma toPython 5       |
|                                |
|o2 = 3.1780538303479458         |
|                                |
|o2 : PythonObject of class float|
+--------------------------------+

See also
========

  * Gamma(PythonObject) -- gamma function of a
    python object

Ways to use this method:
========================

  * lngamma(PythonObject) -- natural
    logarithm of the gamma function of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc/special.m2:93:0.

PythonContext -- persistent Python execution environment
********************************************************

  * Usage:
        new PythonContext
        PythonContext s
        ctx s
  * Inputs:
      * ctx, a Python context,
      * s, a string (Macaulay2Doc),
  * Outputs:
      * a Python context,

Description
===========

The class PythonContext represents a persistent Python execution environment
that maintains its own global namespace. It allows you to evaluate Python
expressions and statements across multiple calls, preserving defined variables
and imports.

When a PythonContext object is created, the given string is executed as Python
code within a new global context.  Subsequent calls evaluate additional Python
code in the same context, allowing variables and imports to persist.

Each evaluation returns a PythonObject, representing the
result of the final expression in the string, if any.

+----------------------------------------------+
|i1 : math = PythonContext "from math import *"|
|                                              |
|o1 = math                                     |
|                                              |
|o1 : PythonContext                            |
+----------------------------------------------+
|i2 : math "x = sin(3.4)"                      |
+----------------------------------------------+
|i3 : math "sin(3.4)"                          |
|                                              |
|o3 = -0.2555411020268312                      |
|                                              |
|o3 : PythonObject of class float              |
+----------------------------------------------+
|i4 : math "x"                                 |
|                                              |
|o4 = -0.2555411020268312                      |
|                                              |
|o4 : PythonObject of class float              |
+----------------------------------------------+
|i5 : math "e"                                 |
|                                              |
|o5 = 2.718281828459045                        |
|                                              |
|o5 : PythonObject of class float              |
+----------------------------------------------+

Here, the import from the Python math module is performed once during
initialization.  The variable x remains available in subsequent calls to the
same PythonContext instance.

Methods that use a Python context:
==================================

  * listSymbols(PythonContext) -- get a
    table of all the variables and their values in a python context
  * "new PythonContext"
  * "new PythonContext from String"
  * "PythonContext String"
  * PythonContext _ String -- get value of
    variable in a python context
  * use(PythonContext) -- install variables from
    a python context

For the programmer
==================

The object PythonContext, is a self initializing type (Macaulay2Doc),
with ancestor classes
MutableHashTable (Macaulay2Doc), < HashTable (Macaulay2Doc)
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc/context.m2:47:0.

PythonContext _ String -- get value of variable in a python context
*******************************************************************

  * Operator: _ (Macaulay2Doc),
  * Usage:
        ctx_s
  * Inputs:
      * ctx, a Python context,
      * s, a string (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

This gets the value of a variable in the given PythonContext.

+----------------------------------------------+
|i1 : math = PythonContext "from math import *"|
|                                              |
|o1 = math                                     |
|                                              |
|o1 : PythonContext                            |
+----------------------------------------------+
|i2 : math "x = sin(3.4)"                      |
+----------------------------------------------+
|i3 : math_"x"                                 |
|                                              |
|o3 = -0.2555411020268312                      |
|                                              |
|o3 : PythonObject of class float              |
+----------------------------------------------+

Ways to use this method:
========================

  * PythonContext _ String -- get value of
    variable in a python context
-------------------------------------------------------------------------------

The source of this document is in Python/doc/context.m2:68:0.

listSymbols(PythonContext) -- get a table of all the variables and their values in a python context
***************************************************************************************************

  * Function: listSymbols (Macaulay2Doc),
  * Usage:
        listSymbols ctx
  * Inputs:
      * ctx, a Python context,

Description
===========

This lists all the symbols and their values in the given PythonContext.

+-----------------------------------------------------------------------------+
|i1 : math = PythonContext "from math import *"                               |
|                                                                             |
|o1 = math                                                                    |
|                                                                             |
|o1 : PythonContext                                                           |
+-----------------------------------------------------------------------------+
|i2 : math "x = sin(3.4)"                                                     |
+-----------------------------------------------------------------------------+
|i3 : listSymbols math                                                        |
|                                                                             |
|o3 = symbol        class                                                     |
|     ------        -----                                                     |
|     __builtins__  dict                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|     acos          builtin_function_or_method                                |
|     acosh         builtin_function_or_method                                |
|     asin          builtin_function_or_method                                |
|     asinh         builtin_function_or_method                                |
|     atan          builtin_function_or_method                                |
|     atan2         builtin_function_or_method                                |
|     atanh         builtin_function_or_method                                |
|     cbrt          builtin_function_or_method                                |
|     ceil          builtin_function_or_method                                |
|     copysign      builtin_function_or_method                                |
|     cos           builtin_function_or_method                                |
|     cosh          builtin_function_or_method                                |
|     degrees       builtin_function_or_method                                |
|     dist          builtin_function_or_method                                |
|     erf           builtin_function_or_method                                |
|     erfc          builtin_function_or_method                                |
|     exp           builtin_function_or_method                                |
|     exp2          builtin_function_or_method                                |
|     expm1         builtin_function_or_method                                |
|     fabs          builtin_function_or_method                                |
|     factorial     builtin_function_or_method                                |
|     floor         builtin_function_or_method                                |
|     fmod          builtin_function_or_method                                |
|     frexp         builtin_function_or_method                                |
|     fsum          builtin_function_or_method                                |
|     gamma         builtin_function_or_method                                |
|     gcd           builtin_function_or_method                                |
|     hypot         builtin_function_or_method                                |
|     isclose       builtin_function_or_method                                |
|     isfinite      builtin_function_or_method                                |
|     isinf         builtin_function_or_method                                |
|     isnan         builtin_function_or_method                                |
|     isqrt         builtin_function_or_method                                |
|     lcm           builtin_function_or_method                                |
|     ldexp         builtin_function_or_method                                |
|     lgamma        builtin_function_or_method                                |
|     log           builtin_function_or_method                                |
|     log1p         builtin_function_or_method                                |
|     log10         builtin_function_or_method                                |
|     log2          builtin_function_or_method                                |
|     modf          builtin_function_or_method                                |
|     pow           builtin_function_or_method                                |
|     radians       builtin_function_or_method                                |
|     remainder     builtin_function_or_method                                |
|     sin           builtin_function_or_method                                |
|     sinh          builtin_function_or_method                                |
|     sqrt          builtin_function_or_method                                |
|     tan           builtin_function_or_method                                |
|     tanh          builtin_function_or_method                                |
|     sumprod       builtin_function_or_method                                |
|     trunc         builtin_function_or_method                                |
|     prod          builtin_function_or_method                                |
|     perm          builtin_function_or_method                                |
|     comb          builtin_function_or_method                                |
|     nextafter     builtin_function_or_method                                |
|     ulp           builtin_function_or_method                                |
|     pi            float                                                     |
|     e             float                                                     |
|     tau           float                                                     |
|     inf           float                                                     |
|     nan           float                                                     |
|     x             float                                                     |
|-----------------------------------------------------------------------------|
|value                                                                        |
|-----                                                                        |
|{'__name__': 'builtins', '__doc__': "Built-in function.                      |
|All Rights Reserved.                                  .                      |
|                                                      .                      |
|.......................................................                      |
|<built-in function acos>                                                     |
|<built-in function acosh>                                                    |
|<built-in function asin>                                                     |
|<built-in function asinh>                                                    |
|<built-in function atan>                                                     |
|<built-in function atan2>                                                    |
|<built-in function atanh>                                                    |
|<built-in function cbrt>                                                     |
|<built-in function ceil>                                                     |
|<built-in function copysign>                                                 |
|<built-in function cos>                                                      |
|<built-in function cosh>                                                     |
|<built-in function degrees>                                                  |
|<built-in function dist>                                                     |
|<built-in function erf>                                                      |
|<built-in function erfc>                                                     |
|<built-in function exp>                                                      |
|<built-in function exp2>                                                     |
|<built-in function expm1>                                                    |
|<built-in function fabs>                                                     |
|<built-in function factorial>                                                |
|<built-in function floor>                                                    |
|<built-in function fmod>                                                     |
|<built-in function frexp>                                                    |
|<built-in function fsum>                                                     |
|<built-in function gamma>                                                    |
|<built-in function gcd>                                                      |
|<built-in function hypot>                                                    |
|<built-in function isclose>                                                  |
|<built-in function isfinite>                                                 |
|<built-in function isinf>                                                    |
|<built-in function isnan>                                                    |
|<built-in function isqrt>                                                    |
|<built-in function lcm>                                                      |
|<built-in function ldexp>                                                    |
|<built-in function lgamma>                                                   |
|<built-in function log>                                                      |
|<built-in function log1p>                                                    |
|<built-in function log10>                                                    |
|<built-in function log2>                                                     |
|<built-in function modf>                                                     |
|<built-in function pow>                                                      |
|<built-in function radians>                                                  |
|<built-in function remainder>                                                |
|<built-in function sin>                                                      |
|<built-in function sinh>                                                     |
|<built-in function sqrt>                                                     |
|<built-in function tan>                                                      |
|<built-in function tanh>                                                     |
|<built-in function sumprod>                                                  |
|<built-in function trunc>                                                    |
|<built-in function prod>                                                     |
|<built-in function perm>                                                     |
|<built-in function comb>                                                     |
|<built-in function nextafter>                                                |
|<built-in function ulp>                                                      |
|3.141592653589793                                                            |
|2.718281828459045                                                            |
|6.283185307179586                                                            |
|inf                                                                          |
|nan                                                                          |
|-0.2555411020268312                                                          |
+-----------------------------------------------------------------------------+

It also works for Python dictionaries.

+---------------------------------------------------+
|i4 : y = toPython hashTable{"foo" => 1, "bar" => 2}|
|                                                   |
|o4 = {'foo': 1, 'bar': 2}                          |
|                                                   |
|o4 : PythonObject of class dict                    |
+---------------------------------------------------+
|i5 : listSymbols y                                 |
|                                                   |
|o5 = symbol  class  value                          |
|     ------  -----  -----                          |
|     foo     int    1                              |
|     bar     int    2                              |
+---------------------------------------------------+

Ways to use this method:
========================

  * listSymbols(PythonContext) -- get a
    table of all the variables and their values in a python context
  * "listSymbols(PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc/context.m2:93:0.

use(PythonContext) -- install variables from a python context
*************************************************************

  * Function: use (Macaulay2Doc),
  * Usage:
        use ctx
  * Inputs:
      * ctx, a Python context,

Description
===========

This method makes all the variables in a PythonContext,
available outside the context.

+------------------------------------------+
|i1 : ctx = new PythonContext              |
|                                          |
|o1 = ctx                                  |
|                                          |
|o1 : PythonContext                        |
+------------------------------------------+
|i2 : ctx "f = lambda x:x**2"              |
+------------------------------------------+
|i3 : ctx "x = 5"                          |
+------------------------------------------+
|i4 : ctx "y = f(x)"                       |
+------------------------------------------+
|i5 : f                                    |
|                                          |
|o5 = f                                    |
|                                          |
|o5 : Symbol                               |
+------------------------------------------+
|i6 : x                                    |
|                                          |
|o6 = x                                    |
|                                          |
|o6 : Symbol                               |
+------------------------------------------+
|i7 : y                                    |
|                                          |
|o7 = y                                    |
|                                          |
|o7 : Symbol                               |
+------------------------------------------+
|i8 : use ctx                              |
+------------------------------------------+
|i9 : f                                    |
|                                          |
|o9 = <function <lambda> at 0x7f809ff58ae0>|
|                                          |
|o9 : PythonObject of class function       |
+------------------------------------------+
|i10 : x                                   |
|                                          |
|o10 = 5                                   |
|                                          |
|o10 : PythonObject of class int           |
+------------------------------------------+
|i11 : y                                   |
|                                          |
|o11 = 25                                  |
|                                          |
|o11 : PythonObject of class int           |
+------------------------------------------+

Ways to use this method:
========================

  * use(PythonContext) -- install variables from
    a python context
-------------------------------------------------------------------------------

The source of this document is in Python/doc/context.m2:120:0.

help(PythonObject) -- documentation for python object
*****************************************************

  * Function: help (Macaulay2Doc),
  * Usage:
        help x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a string (Macaulay2Doc),

Description
===========

This calls Python's built-in help function, which provides documentation for
Python objects.

+-----------------------------------------------------------------------------+
|i1 : math = import "math"                                                    |
|                                                                             |
|o1 = <module 'math' from '/usr/lib64/python3.12/lib-dynload/math.cpython-312-|
|     x86_64-linux-gnu.so'>                                                   |
|                                                                             |
|o1 : PythonObject of class module                                            |
+-----------------------------------------------------------------------------+
|i2 : help math                                                               |
|                                                                             |
|o2 = This module provides access to the mathematical functions               |
|     defined by the C standard.                                              |
+-----------------------------------------------------------------------------+
|i3 : help math@@sin                                                          |
|                                                                             |
|o3 = Return the sine of x (measured in radians).                             |
+-----------------------------------------------------------------------------+

See also
========

  * pythonHelp -- run Python's interactive help utility

Ways to use this method:
========================

  * help(PythonObject) -- documentation for
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:703:0.

pythonHelp -- run Python's interactive help utility
***************************************************

  * Usage:
        pythonHelp

Description
===========

This run's Python's interactive help utility.  Type "quit" when done.

+------------------------------------------------------------------------+
|i1 : pythonHelp                                                         |
|                                                                        |
|Welcome to Python 3.10's help utility!                                  |
|                                                                        |
|If this is your first time using Python, you should definitely check out|
|the tutorial on the internet at https://docs.python.org/3.10/tutorial/. |
|                                                                        |
|Enter the name of any module, keyword, or topic to get help on writing  |
|Python programs and using Python modules.  To quit this help utility and|
|return to the interpreter, just type "quit".                            |
|                                                                        |
|To get a list of available modules, keywords, symbols, or topics, type  |
|"modules", "keywords", "symbols", or "topics".  Each module also comes  |
|with a one-line summary of what it does; to list the modules whose name |
|or summary contain a given string such as "spam", type "modules spam".  |
|                                                                        |
|help> lambda                                                            |
|Lambdas                                                                 |
|*******                                                                 |
|                                                                        |
|   lambda_expr ::= "lambda" [parameter_list] ":" expression             |
|                                                                        |
|Lambda expressions (sometimes called lambda forms) are used to create   |
|anonymous functions. The expression "lambda parameters: expression"     |
|yields a function object.  The unnamed object behaves like a function   |
|object defined with:                                                    |
|                                                                        |
|   def <lambda>(parameters):                                            |
|       return expression                                                |
|                                                                        |
|See section Function definitions for the syntax of parameter lists.     |
|Note that functions created with lambda expressions cannot contain      |
|statements or annotations.                                              |
|                                                                        |
|Related help topics: FUNCTIONS                                          |
|                                                                        |
|help> quit                                                              |
|                                                                        |
|You are now leaving help and returning to the Python interpreter.       |
|If you want to ask for help on a particular object directly from the    |
|interpreter, you can type "help(object)".  Executing "help('string')"   |
|has the same effect as typing a particular string at the help> prompt.  |
|                                                                        |
|o1 = None                                                               |
|                                                                        |
|o1 : PythonObject of class NoneType                                     |
+------------------------------------------------------------------------+

See also
========

  * help(PythonObject) -- documentation for
    python object

For the programmer
==================

The object pythonHelp, is a command (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:764:0.