rewrite introduction

docs/install.rst

@@ -1,3 +1,5 @@
+.. _install:
+
 Installation
 ============
 
@@ -162,17 +164,17 @@ setting can be specified one-off in the form of a prefix::
 
     OMP_NUM_THREADS=1 NUTILS_NPROCS=8 python myscript.py
 
-Consider a faster interpretor
+Consider a faster interpreter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The most commonly used Python interpretor is without doubt the `CPython
+The most commonly used Python interpreter is without doubt the `CPython
 <https://github.com/python/cpython>`_ reference implementation, but it is not
 the only option. Before taking an application in production it may be worth
 testing if `other implementations
 <https://www.python.org/download/alternatives/>`_ have useful performance
 benefits.
 
-One interpretor of note is `Pyston <https://www.pyston.org/>`_, which brings
+One interpreter of note is `Pyston <https://www.pyston.org/>`_, which brings
 just-in-time compilation enhancements that in a typical application can yield a
 20% speed improvement. After Pyston is installed, Nutils and dependencies can
 be installed as before simply replacing ``python`` by ``pyston3``. As packages

docs/intro.rst

@@ -1,113 +1,109 @@
 Getting Started
 ===============
 
-Nutils can be installed via the `Python Package Index
-<https://pypi.org/project/nutils/>`_ or cloned from `Github
-<https://github.com/evalf/nutils>`_. Once properly configured, the best way to
-get going is by reading the :ref:`tutorial` and by studying the :ref:`examples`
-that demonstrate implementations of several solid and fluid mechanics problems.
+The following is a quick guide to running your first Nutils simulation in three
+simple steps.
 
 
-Installation
-------------
-
-Nutils is platform independent and is known to work on Linux, Windows and OS X.
-
-A working installation of Python 3.5 or higher is required. Many different
-installers exist and there are no known issues with any of them. When in doubt
-about which to use, a safe option is to go with the `official installer
-<https://www.python.org/downloads/>`_.
-
-With Python installed, the recommended way to install the latest stable version
-of Nutils is through `pip <https://github.com/pypa/pip>`_ (included in the
-standard installer):
-
-.. code:: sh
+Step 1: Install Nutils
+----------------------
 
-    python3 -m pip install --user nutils
+With Python version 3.5 or newer installed, Nutils and its dependencies can be
+installed via the `Python Package Index <https://pypi.org/project/nutils/>`_
+using the pip package installer. In a terminal window::
 
-By default and without explicitly specifying the source of the given packages,
-pip installs packages from the `Python Package Index
-<https://pypi.org/project/nutils/>`_. To install the latest development version
-of Nutils, pass a zip of branch master of the `official repository
-<https://github.com/evalf/nutils>`_ to pip:
+    python -m pip install --user nutils
 
-.. code:: sh
+Most applications will require `Matplotlib <https://matplotlib.org/>`_ for
+visualization, but since this is not a direct dependency it needs to be
+installed separately::
 
-    python3 -m pip install --user https://github.com/evalf/nutils/archive/master.zip
+    python -m pip install --user matplotlib
 
-To view which version of Nutils is currently installed, run:
+Another useful utility is `BottomBar <https://github.com/evalf/bottombar>`_,
+which Nutils will use to provide runtime information in the bottom line of the
+terminal window::
 
-.. code:: sh
+    python -m pip install --user bottombar
 
-    python3 -m pip show nutils
 
+Step 2: Create a simulation script
+----------------------------------
 
-First steps
------------
+Open a text editor and create a file ``poisson.py`` with the following
+contents:
 
-To confirm Nutils and its dependencies are installed correctly, try to run the
-Laplace example or any of the other examples included in this repostitory. Make
-sure to use the same version of an example as the version of Nutils that is
-currently installed.
+.. code:: python
 
-When running an example from a terminal or editor with Python console, log
-messages should appear in the terminal or console. Simulateneously, a html file
-``log.html`` and any produced figures are written to
-``public_html/<script_name>/yyyy/mm/dd/hh-mm-ss`` in the home directory. In case a
-webserver is running and configured for user directories this automatically
-makes simulations remotely accessible. For convenience,
-``public_html/log.html`` always redirects to the most recent simulation.
+    from nutils import mesh, function, solver, export, cli
 
+    def main(nelems: int = 10):
+      domain, x = mesh.unitsquare(nelems, etype='square')
+      u = function.dotarg('udofs', domain.basis('std', degree=1))
+      g = u.grad(x)
+      J = function.J(x)
+      cons = solver.optimize('udofs',
+        domain.boundary.integral(u**2 * J, degree=2), droptol=1e-12)
+      udofs = solver.optimize('udofs',
+        domain.integral((g @ g / 2 - u) * J, degree=1), constrain=cons)
+      bezier = domain.sample('bezier', 3)
+      x, u = bezier.eval([x, u], udofs=udofs)
+      export.triplot('u.png', x, u, tri=bezier.tri, hull=bezier.hull)
 
-Docker
-------
+    cli.run(main)
 
-`Docker <https://www.docker.com/>`_ container images with the latest and recent
-stable versions of Nutils preinstalled are available from `ghcr.io/evalf/nutils
-<https://github.com/orgs/evalf/packages/container/package/nutils>`_. The
-container images includes all examples in this repository. To run an example,
-add the name of the example and any additional arguments to the command line.
-For example, you can run example ``laplace`` using the latest version of Nutils
-with
+Note that while we could make the script even shorter by avoiding the main
+function and ``cli.run``, the above structure is preferred as it automatically
+sets up a logging environment, activates a matrix backend and handles command
+line parsing.
 
-.. code:: sh
 
-    docker run --rm -it ghcr.io/evalf/nutils:latest laplace
+Step 3: Run the simulation
+--------------------------
 
-HTML log files are generated in the ``/log`` directory of the container. If you
-want to store the log files in ``/path/to/log`` on the host, add ``-v
-/path/to/log:/log`` to the command line before the name of the image. Extending
-the previous example:
+Back in the terminal, the simulation can now be started by running::
 
-.. code:: sh
+    python poisson.py
 
-    docker run --rm -it -v /path/to/log:/log ghcr.io/evalf/nutils:latest laplace
+This should produce the following output::
 
-To run a Python script in this container, bind mount the directory
-containing the script, including all files necessary to run the script,
-to ``/app`` in the container and add the relative path to the script and
-any arguments to the command line. For example, you can run
-``/path/to/script/example.py`` with Docker using
+    nutils v7.0
+    optimize > constrained 40/121 dofs
+    optimize > optimum value 0.00e+00
+    optimize > solve > solving 81 dof system to machine precision using arnoldi solver
+    optimize > solve > solver returned with residual 6e-17
+    optimize > optimum value -1.75e-02
+    u.png
+    log written to file:///home/myusername/public_html/poisson.py/log.html
 
-.. code:: sh
+If the terminal is reasonably modern (Windows users may want to install the new
+`Windows Terminal <https://aka.ms/windowsterminal>`_) then the messages are
+coloured for extra clarity, and a BottomBar will be shown for the duration of
+the simulation.
 
-    docker run --rm -it -v /path/to/script:/app:ro ghcr.io/evalf/nutils:latest example.py
+The last line of the log shows the location of the simultaneously generated
+html file that holds the `same log <_logs/examples%2B2Fpoisson.py/index.html>`_
+as well as a link to the generated image.
 
 
 Next steps and support
 ----------------------
 
-For the numerical background of all examples as well as line by line
-documentation see the overview of :ref:`examples`. Documentation of individual
-functions can be found in the :ref:`api_reference`.
+Be sure to read the :ref:`install` guide for alternative installation methods,
+as well as tips for setting up the broader compute environment.
+
+After that, the best way to get going is by reading the :ref:`tutorial`, to
+familiarize yourself with Nutils' concepts and syntax, and by studying the
+:ref:`examples` that demonstrate implementations of several solid and fluid
+mechanics problems. Most simulations will have components in common with the
+example scripts, so a mix-and-match approach is a good way to start building
+your own script.
 
-Most simulations will have components in common with the example scripts, so a
-mix-and-match approach is a good way to start building your own script. For
-questions that are not answered by the API reference there is the nutils-users
-support channel at `#nutils-users:matrix.org
+Documentation of individual functions can be found in the :ref:`api_reference`.
+For questions that are not answered by the API reference there is the
+nutils-users support channel at `#nutils-users:matrix.org
 <https://matrix.to/#/#nutils-users:matrix.org>`_. Note that you will need to
 create an account at any Matrix server in order to join this channel.
 
-If you are using Nutils in academic research, please consider `citing
+Finally, if you are using Nutils in academic research, please consider `citing
 Nutils <https://doi.org/10.5281/zenodo.822369>`_.