diff --git a/docs/install.rst b/docs/install.rst index 54b0f2cfb..7460e47ec 100644 --- a/docs/install.rst +++ b/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 `_ reference implementation, but it is not the only option. Before taking an application in production it may be worth testing if `other implementations `_ have useful performance benefits. -One interpretor of note is `Pyston `_, which brings +One interpreter of note is `Pyston `_, 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 diff --git a/docs/intro.rst b/docs/intro.rst index 7ff23a761..6c7734c60 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,113 +1,109 @@ Getting Started =============== -Nutils can be installed via the `Python Package Index -`_ or cloned from `Github -`_. 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 -`_. - -With Python installed, the recommended way to install the latest stable version -of Nutils is through `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 `_ +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 -`_. To install the latest development version -of Nutils, pass a zip of branch master of the `official repository -`_ to pip: + python -m pip install --user nutils -.. code:: sh +Most applications will require `Matplotlib `_ 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 `_, +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//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 `_ container images with the latest and recent -stable versions of Nutils preinstalled are available from `ghcr.io/evalf/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 `_) 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 `_. 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 `_.