From a60425f7b787bd53de6e43f836c9fa0ae7ecd168 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Wed, 5 Jun 2024 11:13:59 -0700 Subject: [PATCH 1/5] Start conversion to markdown Converts a few selected pages to markdown, and adds requirements and configuration needed for the conversion. --- conf.py | 24 ++- intro/intro.md | 417 +++++++++++++++++++++++++++++++++++++++++ intro/intro.rst | 472 ----------------------------------------------- requirements.txt | 3 + 4 files changed, 442 insertions(+), 474 deletions(-) create mode 100644 intro/intro.md delete mode 100644 intro/intro.rst diff --git a/conf.py b/conf.py index 464943baf..5f84aff6c 100644 --- a/conf.py +++ b/conf.py @@ -9,7 +9,12 @@ # General configuration # --------------------- -exclude_patterns = ["README.rst"] +exclude_patterns = [ + "README.rst", + ".jupyter_cache", + "jupyter_execute", + "pyximages/README.md", +] # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -23,6 +28,7 @@ "sphinx.ext.extlinks", "sphinx_gallery.gen_gallery", "sphinx_copybutton", + "myst_nb", ] # See https://sphinx-copybutton.readthedocs.io/en/latest/use.html#automatic-exclusion-of-prompts-from-the-copies @@ -72,7 +78,7 @@ templates_path = ["_templates"] # The suffix of source filenames. -source_suffix = ".rst" +source_suffix = [".rst", ".md"] # General information about the project. project = "Scientific Python Lectures" @@ -91,6 +97,18 @@ # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" +# Enable executable .md files support +myst_enable_extensions = [ + 'colon_fence', + 'dollarmath', + 'substitution', + 'tasklist', + 'attrs_inline', + 'linkify', +] + +nb_output_stderr = 'show' + # Monkey-patch sphinx to set the lineseparator option of pygment, to # have indented line wrapping @@ -288,6 +306,8 @@ def add_per_page_js(app, pagename, templatename, context, doctree): def setup(app): + # Do not execute .ipynb files generated by the gallery + app.registry.source_suffix.pop(".ipynb", None) app.add_js_file("https://code.jquery.com/jquery-3.7.0.min.js") app.add_js_file("scroll_highlight_toc.js") diff --git a/intro/intro.md b/intro/intro.md new file mode 100644 index 000000000..a75839438 --- /dev/null +++ b/intro/intro.md @@ -0,0 +1,417 @@ +--- +jupytext: + formats: md:myst + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.2 +kernelspec: + display_name: Python 3 + language: python + name: python3 +--- + +# Python scientific computing ecosystem + +*Authors*: *Fernando Perez, Emmanuelle Gouillart, Gaël Varoquaux, +Valentin Haenel* + +## Why Python? + +### The scientist’s needs + +- Get data (simulation, experiment control), +- Manipulate and process data, +- Visualize results, quickly to understand, but also with high quality + figures, for reports or publications. + +### Python’s strengths + +- **Batteries included** Rich collection of already existing **bricks** + of classic numerical methods, plotting or data processing tools. We + don’t want to re-program the plotting of a curve, a Fourier transform + or a fitting algorithm. Don’t reinvent the wheel! + +- **Easy to learn** Most scientists are not paid as programmers, neither + have they been trained so. They need to be able to draw a curve, smooth + a signal, do a Fourier transform in a few minutes. + +- **Easy communication** To keep code alive within a lab or a company + it should be as readable as a book by collaborators, students, or + maybe customers. Python syntax is simple, avoiding strange symbols or + lengthy routine specifications that would divert the reader from + mathematical or scientific understanding of the code. + +- **Efficient code** Python numerical modules are computationally + efficient. But needless to say that a very fast code becomes useless if + too much time is spent writing it. Python aims for quick development + times and quick execution times. + +- **Universal** Python is a language used for many different problems. + Learning Python avoids learning a new software for each new problem. + +### How does Python compare to other solutions? + +#### Compiled languages: C, C++, Fortran… + +- **Pros** + - Very fast. For heavy computations, it’s difficult to outperform these + languages. +- **Cons** + - Painful usage: no interactivity during development, mandatory compilation + steps, verbose syntax, manual memory management. These are + **difficult languages** for non programmers. + +#### Matlab scripting language + +- **Pros** + - Very rich collection of libraries with numerous algorithms, for many + different domains. Fast execution because these libraries are often written + in a compiled language. + - Pleasant development environment: comprehensive and help, integrated editor, + etc. + - Commercial support is available. +- **Cons** + - Base language is quite poor and can become restrictive for advanced users. + - Not free and not everything is open sourced. + +#### Julia + +- **Pros** + - Fast code, yet interactive and simple. + - Easily connects to Python or C. +- **Cons** + - Ecosystem limited to numerical computing. + - Still young. + +#### Other scripting languages: Scilab, Octave, R, IDL, etc. + +- **Pros** + - Open-source, free, or at least cheaper than Matlab. + - Some features can be very advanced (statistics in R, etc.) +- **Cons** + - Fewer available algorithms than in Matlab, and the language is not more + advanced. + - Some software are dedicated to one domain. Ex: Gnuplot to draw curves. These + programs are very powerful, but they are restricted to a single type of + usage, such as plotting. + +#### Python + +- **Pros** + - Very rich scientific computing libraries + - Well thought out language, allowing to write very readable and well + structured code: we “code what we think”. + - Many libraries beyond scientific computing (web server, serial port access, + etc.) + - Free and open-source software, widely spread, with a vibrant community. + - A variety of powerful environments to work in, such as + - [IPython](https://ipython.readthedocs.io/en/stable/), + - [Spyder](https://www.spyder-ide.org/), + - [Jupyter notebooks](https://jupyter.org/), + - [Pycharm](https://www.jetbrains.com/pycharm), + - [Visual Studio Code](https://code.visualstudio.com/docs/languages/python) +- **Cons** + - Not all the algorithms that can be found in more specialized software or + toolboxes. + +## The scientific Python ecosystem + +Unlike Matlab, or R, Python does not come with a pre-bundled set +of modules for scientific computing. Below are the basic building blocks +that can be combined to obtain a scientific computing environment: + +**Python**, a generic and modern computing language + +- The language: flow control, data types (`string`, `int`), + data collections (lists, dictionaries), etc. + +- Modules of the standard library: string processing, file + management, simple network protocols. + +- A large number of specialized modules or applications written in + Python: web framework, etc. … and scientific + computing. + +- Development tools (automatic testing, documentation generation) + +:::{seealso} +{ref}`chapter on Python language ` +::: + +**Core numeric libraries** + +- **NumPy**: numerical computing with powerful **numerical arrays** + objects, and routines to manipulate them. https://numpy.org/ + + :::{seealso} + {ref}`chapter on numpy ` + ::: + +- **SciPy** : high-level numerical routines. + Optimization, regression, interpolation, etc https://scipy.org/ + + :::{seealso} + {ref}`chapter on SciPy ` + ::: + +- **Matplotlib** : 2-D visualization, “publication-ready” plots + https://matplotlib.org/ + + :::{seealso} + {ref}`chapter on matplotlib ` + ::: + +**Advanced interactive environments**: + +- **IPython**, an advanced **Python console** https://ipython.org/ + +- **Jupyter**, **notebooks** in the browser https://jupyter.org/ + +**Domain-specific packages**, + +- **pandas, statsmodels, seaborn** for {ref}`statistics ` + +- **sympy** for {ref}`symbolic computing ` + +- **scikit-image** for {ref}`image processing ` + +- **scikit-learn** for {ref}`machine learning ` + +and many more packages not documented in the Scientific Python Lectures. + +:::{seealso} +- {ref}`chapters on advanced topics ` +- {ref}`chapters on packages and applications ` +::: + +## Before starting: Installing a working environment + +Python comes in many flavors, and there are many ways to install it. +However, we recommend to install a scientific-computing distribution, +that comes readily with optimized versions of scientific modules. + +**Under Linux** + +If you have a recent distribution, most of the tools are probably +packaged, and it is recommended to use your package manager. + +**Other systems** + +There are several fully-featured scientific Python distributions: + +- [Anaconda](https://www.anaconda.com/download/) +- [WinPython](https://winpython.github.io) + +## The workflow: interactive environments and text editors + +**Interactive work to test and understand algorithms:** In this section, we +describe a workflow combining interactive work and consolidation. + +Python is a general-purpose language. As such, there is not one blessed +environment to work in, and not only one way of using it. Although +this makes it harder for beginners to find their way, it makes it +possible for Python to be used for programs, in web servers, or +embedded devices. + +(interactive_work)= +### Interactive work + +We recommend an interactive work with the [IPython](https://ipython.org) +console, or its offspring, the +[Jupyter notebook](https://docs.jupyter.org/en/latest/content-quickstart.html). +They are handy to explore and understand algorithms. + +In `ipython` or in a Jupyter notebook cell: + +```{code} ipython +In [1]: print('Hello world') +Hello world +``` + +Getting help by using the **?** operator after an object: + +```{code} ipython +In [2]: print? +Signature: print(*args, sep=' ', end='\n', file=None, flush=False) +Docstring: +Prints the values to a stream, or to sys.stdout by default. + +sep + string inserted between values, default a space. +end + string appended after the last value, default a newline. +file + a file-like object (stream); defaults to the current sys.stdout. +flush + whether to forcibly flush the stream. +Type: builtin_function_or_method +``` + +:::{seealso} +- IPython user manual: https://ipython.readthedocs.io/en/stable/ +- Jupyter Notebook QuickStart: https://docs.jupyter.org/en/latest/start/index.html +::: + +### Elaboration of the work in an editor + +As you move forward, it will be important to not only work interactively, +but also to create and reuse Python files. For this, a powerful code editor +will get you far. Here are several good easy-to-use editors: + +- [Spyder](https://www.spyder-ide.org/): integrates an IPython + console, a debugger, a profiler… +- [PyCharm](https://www.jetbrains.com/pycharm): integrates an IPython + console, notebooks, a debugger… (freely available, + but commercial) +- [Visual Studio Code](https://code.visualstudio.com/docs/languages/python): + integrates a Python console, notebooks, a debugger, … + +Some of these are shipped by the various scientific Python distributions, +and you can find them in the menus. + +As an exercise, create a file `my_file.py` in a code editor, and add the +following lines: + +:::{code} ipython +s = 'Hello world' +print(s) +::: + +Now, you can run it in IPython console or a notebook and explore the +resulting variables: + +:::{code} ipython +In [1]: %run my_file.py +Hello world + +In [2]: s +Out[2]: 'Hello world' + +In [3]: %whos +Variable Type Data/Info +---------------------------- +s str Hello world +::: + +:::{note} **From a script to functions** +While it is tempting to work only with scripts, that is a file full +of instructions following each other, do plan to progressively evolve +the script to a set of functions: + +- A script is not reusable, functions are. + +- Thinking in terms of functions helps breaking the problem in small + blocks. +::: + +#### IPython and Jupyter Tips and Tricks + +The user manuals contain a wealth of information. Here we give a quick +introduction to four useful features: *history*, *tab completion*, *magic +functions*, and *aliases*. + +**Command history** Like a UNIX shell, the IPython console supports +command history. Type *up* and *down* to navigate previously typed +commands: + +:::{code} ipython +In [1]: x = 10 + +In [2]: + +In [2]: x = 10 +::: + +**Tab completion** Tab completion, is a convenient way to explore the +structure of any object you’re dealing with. Simply type object_name. to +view the object’s attributes. Besides Python objects and keywords, tab +completion also works on file and directory names. + +:::{code} ipython +In [1]: x = 10 + +In [2]: x. + as_integer_ratio() conjugate() imag to_bytes() + bit_count() denominator numerator + bit_length() from_bytes() real +::: + +**Magic functions** +The console and the notebooks support so-called *magic* functions by prefixing a command with the +`%` character. For example, the `run` and `whos` functions from the +previous section are magic functions. Note that, the setting `automagic`, +which is enabled by default, allows you to omit the preceding `%` sign. Thus, +you can just type the magic function and it will work. + +Other useful magic functions are: + +- `%cd` to change the current directory. + + :::{code} ipython + + In [1]: cd /tmp + /tmp + ::: + +- `%cpaste` allows you to paste code, especially code from websites which has + been prefixed with the standard Python prompt (e.g. `>>>`) or with an ipython + prompt, (e.g. `in [3]`): + + :::{code} ipython + + In [2]: %cpaste + Pasting code; enter '--' alone on the line to stop or use Ctrl-D. + :for i in range(3): + print(i): + :-- + 0 + 1 + 2 + ::: + +- `%timeit` allows you to time the execution of short snippets using the + `timeit` module from the standard library: + + :::{code} ipython + In [3]: %timeit x = 10 + 10000000 loops, best of 3: 39 ns per loop + ::: + + :::{seealso} {ref}`Chapter on optimizing code ` + ::: + +- `%debug` allows you to enter post-mortem debugging. That is to say, if the + code you try to execute, raises an exception, using `%debug` will enter the + debugger at the point where the exception was thrown. + + :::{code} ipython + In [4]: x === 10 + + In [5]: %debug + > /home/jarrod/.venv/lectures/lib64/python3.11/site-packages/IPython/core/compilerop.py(86)ast_parse() + 84 Arguments are exactly the same as ast.parse (in the standard library), + 85 and are passed to the built-in compile function.""" + ---> 86 return compile(source, filename, symbol, self.flags | PyCF_ONLY_AST, 1) + 87 + 88 def reset_compiler_flags(self): + ipdb> locals() + {'self': , 'source': 'x === 10\n', 'filename': '', 'symbol': 'exec'} + ipdb> + ::: + + :::{seealso} {ref}`Chapter on debugging ` + +**Aliases** +Furthermore IPython ships with various *aliases* which emulate common UNIX +command line tools such as `ls` to list files, `cp` to copy files and `rm` to +remove files (a full list of aliases is shown when typing `alias`). + +:::{tip} **Getting help** + + * The built-in cheat-sheet is accessible via the ``%quickref`` magic + function. + + * A list of all available magic functions is shown when typing ``%magic``. +::: diff --git a/intro/intro.rst b/intro/intro.rst deleted file mode 100644 index 8f09cf2bd..000000000 --- a/intro/intro.rst +++ /dev/null @@ -1,472 +0,0 @@ -Python scientific computing ecosystem -====================================== - -**Authors**: *Fernando Perez, Emmanuelle Gouillart, Gaël Varoquaux, -Valentin Haenel* - -Why Python? ------------- - -The scientist's needs -....................... - -* Get data (simulation, experiment control), - -* Manipulate and process data, - -* Visualize results, quickly to understand, but also with high quality - figures, for reports or publications. - -Python's strengths -.................. - -* **Batteries included** Rich collection of already existing **bricks** - of classic numerical methods, plotting or data processing tools. We - don't want to re-program the plotting of a curve, a Fourier transform - or a fitting algorithm. Don't reinvent the wheel! - -* **Easy to learn** Most scientists are not paid as programmers, neither - have they been trained so. They need to be able to draw a curve, smooth - a signal, do a Fourier transform in a few minutes. - -* **Easy communication** To keep code alive within a lab or a company - it should be as readable as a book by collaborators, students, or - maybe customers. Python syntax is simple, avoiding strange symbols or - lengthy routine specifications that would divert the reader from - mathematical or scientific understanding of the code. - -* **Efficient code** Python numerical modules are computationally - efficient. But needless to say that a very fast code becomes useless if - too much time is spent writing it. Python aims for quick development - times and quick execution times. - -* **Universal** Python is a language used for many different problems. - Learning Python avoids learning a new software for each new problem. - -How does Python compare to other solutions? -............................................ - -Compiled languages: C, C++, Fortran... -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Pros: - - * Very fast. For heavy computations, it's difficult to outperform these - languages. - -:Cons: - - * Painful usage: no interactivity during development, mandatory - compilation steps, verbose syntax, manual memory management. These - are **difficult languages** for non programmers. - -Matlab scripting language -~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Pros: - - * Very rich collection of libraries with numerous algorithms, for many - different domains. Fast execution because these libraries are often written - in a compiled language. - - * Pleasant development environment: comprehensive and help, integrated - editor, etc. - - * Commercial support is available. - -:Cons: - - * Base language is quite poor and can become restrictive for advanced users. - - * Not free and not everything is open sourced. - -Julia -~~~~~~~ - -:Pros: - - * Fast code, yet interactive and simple. - - * Easily connects to Python or C. - -:Cons: - - * Ecosystem limited to numerical computing. - - * Still young. - -Other scripting languages: Scilab, Octave, R, IDL, etc. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Pros: - - * Open-source, free, or at least cheaper than Matlab. - - * Some features can be very advanced (statistics in R, etc.) - -:Cons: - - * Fewer available algorithms than in Matlab, and the language - is not more advanced. - - * Some software are dedicated to one domain. Ex: Gnuplot to draw - curves. These programs are very powerful, but they are restricted to - a single type of usage, such as plotting. - -Python -~~~~~~ - -:Pros: - - * Very rich scientific computing libraries - - * Well thought out language, allowing to write very readable and well - structured code: we "code what we think". - - * Many libraries beyond scientific computing (web server, - serial port access, etc.) - - * Free and open-source software, widely spread, with a vibrant community. - - * A variety of powerful environments to work in, such as - `IPython `__, - `Spyder `__, - `Jupyter notebooks `__, - `Pycharm `__, - `Visual Studio Code `__ - -:Cons: - - * Not all the algorithms that can be found in more specialized - software or toolboxes. - -The scientific Python ecosystem -------------------------------- - -Unlike Matlab, or R, Python does not come with a pre-bundled set -of modules for scientific computing. Below are the basic building blocks -that can be combined to obtain a scientific computing environment: - -| - -**Python**, a generic and modern computing language - -* The language: flow control, data types (``string``, ``int``), - data collections (lists, dictionaries), etc. - -* Modules of the standard library: string processing, file - management, simple network protocols. - -* A large number of specialized modules or applications written in - Python: web framework, etc. ... and scientific - computing. - -* Development tools (automatic testing, documentation generation) - -.. seealso:: - - :ref:`chapter on Python language ` - -**Core numeric libraries** - -* **NumPy**: numerical computing with powerful **numerical arrays** - objects, and routines to manipulate them. https://numpy.org/ - - .. seealso:: - - :ref:`chapter on numpy ` - -* **SciPy** : high-level numerical routines. - Optimization, regression, interpolation, etc https://scipy.org/ - - .. seealso:: - - :ref:`chapter on SciPy ` - -* **Matplotlib** : 2-D visualization, "publication-ready" plots - https://matplotlib.org/ - - .. seealso:: - - :ref:`chapter on matplotlib ` - -**Advanced interactive environments**: - -* **IPython**, an advanced **Python console** https://ipython.org/ - -* **Jupyter**, **notebooks** in the browser https://jupyter.org/ - - -**Domain-specific packages**, - -* **pandas, statsmodels, seaborn** for :ref:`statistics ` - -* **sympy** for :ref:`symbolic computing ` - -* **scikit-image** for :ref:`image processing ` - -* **scikit-learn** for :ref:`machine learning ` - -and many more packages not documented in the Scientific Python Lectures. - -.. seealso:: - - :ref:`chapters on advanced topics ` - - :ref:`chapters on packages and applications ` - -|clear-floats| - -.. - >>> import numpy as np - - -Before starting: Installing a working environment --------------------------------------------------- -Python comes in many flavors, and there are many ways to install it. -However, we recommend to install a scientific-computing distribution, -that comes readily with optimized versions of scientific modules. - -**Under Linux** - -If you have a recent distribution, most of the tools are probably -packaged, and it is recommended to use your package manager. - -**Other systems** - -There are several fully-featured scientific Python distributions: - - -.. rst-class:: horizontal - - * `Anaconda `_ - * `WinPython `_ - - -The workflow: interactive environments and text editors ----------------------------------------------------------- - -**Interactive work to test and understand algorithms:** In this section, we -describe a workflow combining interactive work and consolidation. - -Python is a general-purpose language. As such, there is not one blessed -environment to work in, and not only one way of using it. Although -this makes it harder for beginners to find their way, it makes it -possible for Python to be used for programs, in web servers, or -embedded devices. - -.. _interactive_work: - -Interactive work -................. - -We recommend an interactive work with the `IPython -`__ console, or its offspring, the `Jupyter notebook -`_. They -are handy to explore and understand algorithms. - -.. sidebar:: Under the notebook - - To execute code, press "shift enter" - -Start `ipython`: - -.. ipython:: - :verbatim: - - In [1]: print('Hello world') - Hello world - -Getting help by using the **?** operator after an object: - -.. ipython:: - - In [1]: print? - -.. seealso:: - - * IPython user manual: https://ipython.readthedocs.io/en/stable/ - - * Jupyter Notebook QuickStart: - https://docs.jupyter.org/en/latest/start/index.html - -Elaboration of the work in an editor -.......................................... - -As you move forward, it will be important to not only work interactively, -but also to create and reuse Python files. For this, a powerful code editor -will get you far. Here are several good easy-to-use editors: - - * `Spyder `_: integrates an IPython - console, a debugger, a profiler... - * `PyCharm `_: integrates an IPython - console, notebooks, a debugger... (freely available, - but commercial) - * `Visual Studio Code `_: - integrates a Python console, notebooks, a debugger, ... - -Some of these are shipped by the various scientific Python distributions, -and you can find them in the menus. - - -As an exercise, create a file `my_file.py` in a code editor, and add the -following lines:: - - s = 'Hello world' - print(s) - -Now, you can run it in IPython console or a notebook and explore the -resulting variables: - -.. ipython:: - - @suppress - In [1]: s = 'Hello world' - - @verbatim - In [1]: %run my_file.py - Hello world - - @doctest - In [2]: s - Out[2]: 'Hello world' - - @verbatim - In [3]: %whos - Variable Type Data/Info - ---------------------------- - s str Hello world - - -.. topic:: **From a script to functions** - - While it is tempting to work only with scripts, that is a file full - of instructions following each other, do plan to progressively evolve - the script to a set of functions: - - * A script is not reusable, functions are. - - * Thinking in terms of functions helps breaking the problem in small - blocks. - - -IPython and Jupyter Tips and Tricks -.................................... - -The user manuals contain a wealth of information. Here we give a quick -introduction to four useful features: *history*, *tab completion*, *magic -functions*, and *aliases*. - -| - -**Command history** Like a UNIX shell, the IPython console supports -command history. Type *up* and *down* to navigate previously typed -commands: - -.. ipython:: - - In [1]: x = 10 - - @verbatim - In [2]: - - In [2]: x = 10 - -| - -**Tab completion** Tab completion, is a convenient way to explore the -structure of any object you’re dealing with. Simply type object_name. to -view the object’s attributes. Besides Python objects and keywords, tab -completion also works on file and directory names.* - -.. ipython:: - - In [1]: x = 10 - - @verbatim - In [2]: x. - as_integer_ratio() conjugate() imag to_bytes() - bit_count() denominator numerator - bit_length() from_bytes() real - -| - -**Magic functions** -The console and the notebooks support so-called *magic* functions by prefixing a command with the -``%`` character. For example, the ``run`` and ``whos`` functions from the -previous section are magic functions. Note that, the setting ``automagic``, -which is enabled by default, allows you to omit the preceding ``%`` sign. Thus, -you can just type the magic function and it will work. - -Other useful magic functions are: - -* ``%cd`` to change the current directory. - - .. ipython:: - - In [1]: cd /tmp - /tmp - -* ``%cpaste`` allows you to paste code, especially code from websites which has - been prefixed with the standard Python prompt (e.g. ``>>>``) or with an ipython - prompt, (e.g. ``in [3]``): - - .. ipython:: - - In [2]: %cpaste - Pasting code; enter '--' alone on the line to stop or use Ctrl-D. - :>>> for i in range(3): - :... print(i) - :-- - 0 - 1 - 2 - -* ``%timeit`` allows you to time the execution of short snippets using the - ``timeit`` module from the standard library: - - .. ipython:: - - In [3]: %timeit x = 10 - 10000000 loops, best of 3: 39 ns per loop - - .. seealso:: :ref:`Chapter on optimizing code ` - -* ``%debug`` allows you to enter post-mortem debugging. That is to say, if the - code you try to execute, raises an exception, using ``%debug`` will enter the - debugger at the point where the exception was thrown. - - .. ipython:: - :okexcept: - - In [4]: x === 10 - - @verbatim - In [5]: %debug - > /home/jarrod/.venv/lectures/lib64/python3.11/site-packages/IPython/core/compilerop.py(86)ast_parse() - 84 Arguments are exactly the same as ast.parse (in the standard library), - 85 and are passed to the built-in compile function.""" - ---> 86 return compile(source, filename, symbol, self.flags | PyCF_ONLY_AST, 1) - 87 - 88 def reset_compiler_flags(self): - ipdb> locals() - {'self': , 'source': 'x === 10\n', 'filename': '', 'symbol': 'exec'} - ipdb> - - .. seealso:: :ref:`Chapter on debugging ` - -| - -**Aliases** -Furthermore IPython ships with various *aliases* which emulate common UNIX -command line tools such as ``ls`` to list files, ``cp`` to copy files and ``rm`` to -remove files (a full list of aliases is shown when typing ``alias``). - -.. topic:: **Getting help** - - * The built-in cheat-sheet is accessible via the ``%quickref`` magic - function. - - * A list of all available magic functions is shown when typing ``%magic``. - -.. :vim:spell: diff --git a/requirements.txt b/requirements.txt index 30a050206..b73910625 100644 --- a/requirements.txt +++ b/requirements.txt @@ -21,3 +21,6 @@ pickleshare pre-commit==3.7.1 requests sphinxcontrib-jquery +myst-nb +jupytext +linkify-it-py From cb4982a4687db09433865b00420cdf975452ed48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Sun, 14 Jul 2024 17:27:12 -0300 Subject: [PATCH 2/5] Remove duplicated gallery in advanced/mathematical_optimization --- advanced/mathematical_optimization/index.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/advanced/mathematical_optimization/index.rst b/advanced/mathematical_optimization/index.rst index b59801aaa..2cb177da7 100644 --- a/advanced/mathematical_optimization/index.rst +++ b/advanced/mathematical_optimization/index.rst @@ -540,23 +540,12 @@ each step an approximation of the Hessian. .. |bfgs_gauss_icond_conv| image:: auto_examples/images/sphx_glr_plot_gradient_descent_032.png :scale: 75% -Full code examples -================== - -.. include the gallery. Skip the first line to avoid the "orphan" - declaration - -.. include:: auto_examples/index.rst - :start-line: 1 - - .. |bfgs_rosen_icond| image:: auto_examples/images/sphx_glr_plot_gradient_descent_014.png :scale: 90% .. |bfgs_rosen_icond_conv| image:: auto_examples/images/sphx_glr_plot_gradient_descent_033.png :scale: 75% - .. list-table:: :widths: 1 1 1 From 6c8842b61b7e0f36af0fc2ec4a799cac65459501 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Sun, 14 Jul 2024 17:28:23 -0300 Subject: [PATCH 3/5] Update .gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index e588efd0a..a1529f546 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,6 @@ airfares.txt wages.txt ScientificPythonLectures-simple.pdf ScientificPythonLectures.pdf +junk.txt +sg_execution_times.rst +test.pkl From 0bebd447d2a4c621c5893187150cde538131185a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Sun, 28 Jul 2024 16:23:52 -0300 Subject: [PATCH 4/5] Set ipython block to verbatim to avoid LaTeX failure --- intro/language/standard_library.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/intro/language/standard_library.rst b/intro/language/standard_library.rst index 12d5d4f97..0f1ed5aba 100644 --- a/intro/language/standard_library.rst +++ b/intro/language/standard_library.rst @@ -153,6 +153,7 @@ Walking a directory ``os.path.walk`` generates a list of filenames in a directory tree. .. ipython:: + :verbatim: In [10]: for dirpath, dirnames, filenames in os.walk(os.curdir): ....: for fp in filenames: From 5f7179be16379a6fac4c00e3d72872213e59c3a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 18 Oct 2024 09:21:53 -0300 Subject: [PATCH 5/5] Fix linting issues --- conf.py | 13 ++-- intro/intro.md | 187 ++++++++++++++++++++++++------------------------- 2 files changed, 99 insertions(+), 101 deletions(-) diff --git a/conf.py b/conf.py index 316605ddd..52d181a88 100644 --- a/conf.py +++ b/conf.py @@ -99,15 +99,14 @@ # Enable executable .md files support myst_enable_extensions = [ - 'colon_fence', - 'dollarmath', - 'substitution', - 'tasklist', - 'attrs_inline', - 'linkify', + "colon_fence", + "dollarmath", + "substitution", + "tasklist", + "attrs_inline", ] -nb_output_stderr = 'show' +nb_output_stderr = "show" # Monkey-patch sphinx to set the lineseparator option of pygment, to # have indented line wrapping diff --git a/intro/intro.md b/intro/intro.md index a75839438..6897202da 100644 --- a/intro/intro.md +++ b/intro/intro.md @@ -14,8 +14,8 @@ kernelspec: # Python scientific computing ecosystem -*Authors*: *Fernando Perez, Emmanuelle Gouillart, Gaël Varoquaux, -Valentin Haenel* +_Authors_: _Fernando Perez, Emmanuelle Gouillart, Gaël Varoquaux, +Valentin Haenel_ ## Why Python? @@ -29,27 +29,27 @@ Valentin Haenel* ### Python’s strengths - **Batteries included** Rich collection of already existing **bricks** - of classic numerical methods, plotting or data processing tools. We - don’t want to re-program the plotting of a curve, a Fourier transform - or a fitting algorithm. Don’t reinvent the wheel! + of classic numerical methods, plotting or data processing tools. We + don’t want to re-program the plotting of a curve, a Fourier transform + or a fitting algorithm. Don’t reinvent the wheel! - **Easy to learn** Most scientists are not paid as programmers, neither - have they been trained so. They need to be able to draw a curve, smooth - a signal, do a Fourier transform in a few minutes. + have they been trained so. They need to be able to draw a curve, smooth + a signal, do a Fourier transform in a few minutes. - **Easy communication** To keep code alive within a lab or a company - it should be as readable as a book by collaborators, students, or - maybe customers. Python syntax is simple, avoiding strange symbols or - lengthy routine specifications that would divert the reader from - mathematical or scientific understanding of the code. + it should be as readable as a book by collaborators, students, or + maybe customers. Python syntax is simple, avoiding strange symbols or + lengthy routine specifications that would divert the reader from + mathematical or scientific understanding of the code. - **Efficient code** Python numerical modules are computationally - efficient. But needless to say that a very fast code becomes useless if - too much time is spent writing it. Python aims for quick development - times and quick execution times. + efficient. But needless to say that a very fast code becomes useless if + too much time is spent writing it. Python aims for quick development + times and quick execution times. - **Universal** Python is a language used for many different problems. - Learning Python avoids learning a new software for each new problem. + Learning Python avoids learning a new software for each new problem. ### How does Python compare to other solutions? @@ -124,17 +124,16 @@ that can be combined to obtain a scientific computing environment: **Python**, a generic and modern computing language -- The language: flow control, data types (`string`, `int`), - data collections (lists, dictionaries), etc. +- The language: flow control, data types (`string`, `int`), + data collections (lists, dictionaries), etc. -- Modules of the standard library: string processing, file - management, simple network protocols. +- Modules of the standard library: string processing, file + management, simple network protocols. -- A large number of specialized modules or applications written in - Python: web framework, etc. … and scientific - computing. +- A large number of specialized modules or applications written in + Python: web framework, etc. ... and scientific computing. -- Development tools (automatic testing, documentation generation) +- Development tools (automatic testing, documentation generation) :::{seealso} {ref}`chapter on Python language ` @@ -142,42 +141,42 @@ that can be combined to obtain a scientific computing environment: **Core numeric libraries** -- **NumPy**: numerical computing with powerful **numerical arrays** - objects, and routines to manipulate them. https://numpy.org/ +- **NumPy**: numerical computing with powerful **numerical arrays** + objects, and routines to manipulate them. https://numpy.org/ - :::{seealso} - {ref}`chapter on numpy ` - ::: + :::{seealso} + {ref}`chapter on numpy ` + ::: -- **SciPy** : high-level numerical routines. - Optimization, regression, interpolation, etc https://scipy.org/ +- **SciPy** : high-level numerical routines. + Optimization, regression, interpolation, etc https://scipy.org/ - :::{seealso} - {ref}`chapter on SciPy ` - ::: + :::{seealso} + {ref}`chapter on SciPy ` + ::: -- **Matplotlib** : 2-D visualization, “publication-ready” plots - https://matplotlib.org/ +- **Matplotlib** : 2-D visualization, “publication-ready” plots + https://matplotlib.org/ - :::{seealso} - {ref}`chapter on matplotlib ` - ::: + :::{seealso} + {ref}`chapter on matplotlib ` + ::: **Advanced interactive environments**: -- **IPython**, an advanced **Python console** https://ipython.org/ +- **IPython**, an advanced **Python console** https://ipython.org/ -- **Jupyter**, **notebooks** in the browser https://jupyter.org/ +- **Jupyter**, **notebooks** in the browser https://jupyter.org/ **Domain-specific packages**, -- **pandas, statsmodels, seaborn** for {ref}`statistics ` +- **pandas, statsmodels, seaborn** for {ref}`statistics ` -- **sympy** for {ref}`symbolic computing ` +- **sympy** for {ref}`symbolic computing ` -- **scikit-image** for {ref}`image processing ` +- **scikit-image** for {ref}`image processing ` -- **scikit-learn** for {ref}`machine learning ` +- **scikit-learn** for {ref}`machine learning ` and many more packages not documented in the Scientific Python Lectures. @@ -216,6 +215,7 @@ possible for Python to be used for programs, in web servers, or embedded devices. (interactive_work)= + ### Interactive work We recommend an interactive work with the [IPython](https://ipython.org) @@ -261,12 +261,11 @@ but also to create and reuse Python files. For this, a powerful code editor will get you far. Here are several good easy-to-use editors: - [Spyder](https://www.spyder-ide.org/): integrates an IPython - console, a debugger, a profiler… + console, a debugger, a profiler… - [PyCharm](https://www.jetbrains.com/pycharm): integrates an IPython - console, notebooks, a debugger… (freely available, - but commercial) + console, notebooks, a debugger… (freely available, but commercial) - [Visual Studio Code](https://code.visualstudio.com/docs/languages/python): - integrates a Python console, notebooks, a debugger, … + integrates a Python console, notebooks, a debugger, ... Some of these are shipped by the various scientific Python distributions, and you can find them in the menus. @@ -309,11 +308,11 @@ the script to a set of functions: #### IPython and Jupyter Tips and Tricks The user manuals contain a wealth of information. Here we give a quick -introduction to four useful features: *history*, *tab completion*, *magic -functions*, and *aliases*. +introduction to four useful features: _history_, _tab completion_, _magic +functions_, and _aliases_. **Command history** Like a UNIX shell, the IPython console supports -command history. Type *up* and *down* to navigate previously typed +command history. Type _up_ and _down_ to navigate previously typed commands: :::{code} ipython @@ -347,64 +346,64 @@ you can just type the magic function and it will work. Other useful magic functions are: -- `%cd` to change the current directory. +- `%cd` to change the current directory. - :::{code} ipython + :::{code} ipython - In [1]: cd /tmp - /tmp - ::: + In [1]: cd /tmp + /tmp + ::: -- `%cpaste` allows you to paste code, especially code from websites which has - been prefixed with the standard Python prompt (e.g. `>>>`) or with an ipython - prompt, (e.g. `in [3]`): +- `%cpaste` allows you to paste code, especially code from websites which has + been prefixed with the standard Python prompt (e.g. `>>>`) or with an ipython + prompt, (e.g. `in [3]`): - :::{code} ipython + :::{code} ipython - In [2]: %cpaste - Pasting code; enter '--' alone on the line to stop or use Ctrl-D. - :for i in range(3): - print(i): - :-- - 0 - 1 - 2 - ::: + In [2]: %cpaste + Pasting code; enter '--' alone on the line to stop or use Ctrl-D. + :for i in range(3): + print(i): + :-- + 0 + 1 + 2 + ::: -- `%timeit` allows you to time the execution of short snippets using the - `timeit` module from the standard library: +- `%timeit` allows you to time the execution of short snippets using the + `timeit` module from the standard library: - :::{code} ipython - In [3]: %timeit x = 10 - 10000000 loops, best of 3: 39 ns per loop - ::: + :::{code} ipython + In [3]: %timeit x = 10 + 10000000 loops, best of 3: 39 ns per loop + ::: - :::{seealso} {ref}`Chapter on optimizing code ` - ::: + :::{seealso} {ref}`Chapter on optimizing code ` + ::: -- `%debug` allows you to enter post-mortem debugging. That is to say, if the - code you try to execute, raises an exception, using `%debug` will enter the - debugger at the point where the exception was thrown. +- `%debug` allows you to enter post-mortem debugging. That is to say, if the + code you try to execute, raises an exception, using `%debug` will enter the + debugger at the point where the exception was thrown. - :::{code} ipython - In [4]: x === 10 + :::{code} ipython + In [4]: x === 10 - In [5]: %debug - > /home/jarrod/.venv/lectures/lib64/python3.11/site-packages/IPython/core/compilerop.py(86)ast_parse() - 84 Arguments are exactly the same as ast.parse (in the standard library), - 85 and are passed to the built-in compile function.""" - ---> 86 return compile(source, filename, symbol, self.flags | PyCF_ONLY_AST, 1) - 87 - 88 def reset_compiler_flags(self): - ipdb> locals() - {'self': , 'source': 'x === 10\n', 'filename': '', 'symbol': 'exec'} - ipdb> - ::: + In [5]: %debug + > /home/jarrod/.venv/lectures/lib64/python3.11/site-packages/IPython/core/compilerop.py(86)ast_parse() + 84 Arguments are exactly the same as ast.parse (in the standard library), + 85 and are passed to the built-in compile function.""" + ---> 86 return compile(source, filename, symbol, self.flags | PyCF_ONLY_AST, 1) + 87 + 88 def reset_compiler_flags(self): + ipdb> locals() + {'self': , 'source': 'x === 10\n', 'filename': '', 'symbol': 'exec'} + ipdb> + ::: :::{seealso} {ref}`Chapter on debugging ` **Aliases** -Furthermore IPython ships with various *aliases* which emulate common UNIX +Furthermore IPython ships with various _aliases_ which emulate common UNIX command line tools such as `ls` to list files, `cp` to copy files and `rm` to remove files (a full list of aliases is shown when typing `alias`).