Docu update (#697)

* updated installation, interface tutorial

* added develop build to installation, refined gd interface tutorial

doc/install/getting-started.rst

@@ -1,7 +1,7 @@
 Getting started with AMUSE
 ==========================
 
-AMUSE is based on python, so if you’re new to Python, you’ll find the official `Python documentation <https://docs.python.org/3/>` a valuable resource. Like with Python, there are basically two ways to use AMUSE. Firstly, directly via the interactive (Python) command line:
+AMUSE is based on python, so if you’re new to Python, you’ll find the official `Python documentation <https://docs.python.org/3/>`_ a valuable resource. Like with Python, there are basically two ways to use AMUSE. Firstly, directly via the interactive (Python) command line:
 
 .. code-block:: sh
 

doc/install/howto-install-AMUSE.rst

@@ -18,7 +18,8 @@ In the examples below we choose GCC-7 as the compiler, but more recent versions
       libgsl-dev cmake libfftw3-3 libfftw3-dev \
       libgmp3-dev libmpfr6 libmpfr-dev \
       libhdf5-serial-dev hdf5-tools \
-      git
+      libblas-dev liblapack-dev \
+      python3-venv python3-pip git
 
 * For mpich:
 
@@ -29,7 +30,8 @@ In the examples below we choose GCC-7 as the compiler, but more recent versions
       libgsl-dev cmake libfftw3-3 libfftw3-dev \
       libgmp3-dev libmpfr6 libmpfr-dev \
       libhdf5-serial-dev hdf5-tools \
-      git
+      libblas-dev liblapack-dev \
+      python3-venv python3-pip git
 
 
 macOS
@@ -48,7 +50,7 @@ In the examples below we choose GCC 9 as the compiler, but other versions of GCC
 
 .. code-block:: sh
 
-    sudo port install gcc9 openmpi-gcc9 hdf5 gsl cmake gmp mpfr fftw-3 +gcc9
+    sudo port install gcc9 openmpi-gcc9 hdf5 gsl cmake gmp mpfr fftw-3 +gcc9 openblas lapack
     sudo port install python38
     sudo port select --set mpi openmpi-gcc9-fortran
     sudo port select --set gcc mp-gcc9
@@ -58,7 +60,7 @@ In the examples below we choose GCC 9 as the compiler, but other versions of GCC
 
 .. code-block:: sh
 
-    sudo port install gcc9 mpich-gcc9 hdf5 gsl cmake gmp mpfr fftw-3 +gcc9
+    sudo port install gcc9 mpich-gcc9 hdf5 gsl cmake gmp mpfr fftw-3 +gcc9 openblas lapack
     sudo port install python38
     sudo port select --set mpi mpich-gcc9
     sudo port select --set gcc mp-gcc9
@@ -98,13 +100,15 @@ Now you can use pip to install the prerequisite python modules for AMUSE:
 
 .. code-block:: sh
 
-    pip install numpy nose docutils mpi4py h5py wheel
+    pip install --upgrade pip
+
+    pip install numpy docutils mpi4py h5py wheel
 
 Probably, you’ll want to install these Python modules too:
 
 .. code-block:: sh
 
-    pip install scipy astropy jupyter pandas seaborn
+    pip install scipy astropy jupyter pandas seaborn matplotlib
 
 Now we can finally install AMUSE itself.
 This is done easiest via pip:
@@ -121,3 +125,40 @@ If you only require a subset of AMUSE, you can install any of the individual pac
     pip install amuse-framework
     pip install amuse-$(community_code_name)
 
+
+
+Re-installation notes and troubleshooting pip installs
+******************************************************
+
+The packages installed with pip are distributed as source packages that must be compiled against the libraries
+installed on your local machine. After compilation pip saves a binary package version in its cache.
+In case of problems with the AMUSE installation using pip or if the environment changes it may be necessary to clean the pip cache (e.g. at ```~/.cache/pip```). In addition, the cache can be disabled using the ```--no-cache-dir``` option. the ```--no-build-isolation``` may also be tried in case the virtualenv has all the prerequisites, but the build still fails.
+The ```--no-clean``` pip install option preserves the build directory for debugging purposes (The actual directory is reported 
+in verbose mode ```-v```). 
+
+
+
+Development build
+*****************
+
+Alternatively, you can install amuse as a development build, which allows you to modify the source code. It is potentially also more convenient when encountering issues with installation of specific codes as the build.log file in the root directory of the repository contains the error logs of the installation process.
+
+Installation can also be handled through pip by executing (in the root of a clone of the repository)
+
+.. code-block:: sh
+
+    pip install -e .
+
+after this the codes need to be build:
+
+.. code-block:: sh
+
+    python setup.py develop_build
+
+individual codes can be build with:
+
+.. code-block:: sh
+
+    make {code}.code
+
+with {code} the name of the code in lower case. 

doc/install/index.rst

@@ -6,7 +6,5 @@ Installation
 
    howto-install-AMUSE
    getting-started
-   configuration
-   documenting
 
 

doc/tutorial/gravitational_dynamics_code.rst

@@ -24,8 +24,6 @@ The Legacy Code
 For this example we will use a very simple forward Eulerian integration routine as our
 legacy code. We simply have a function that takes the initial condition of a set of particles (in the form of seven dynamic arrays), an integer containing the number of particles, and double precision scalars containing the time step, smoothing length, and gravitational constant. It outputs the new particle positions and velocities by updating the input arrays.
 
-SimpleGrav.cc goes here.
-
 .. literalinclude:: simplegrav/SimpleGrav.cc
     :language: C++
 
@@ -154,7 +152,6 @@ synchronize_model           evolve all particles to the same time, if they
 The following code contains definitions for all legacy functions, although some
 non-essential functions only return error values:
 
-interface_1.cc goes here.
 
 .. literalinclude:: simplegrav/interface_1.cc
     :language: C++
@@ -211,9 +208,41 @@ Parameters are added as follows:
 Here, ``get_parameter`` and ``set_parameter`` are two legacy interface functions
 that respectively have one output and one input. ``parameter`` is the name of the
 parameter in the code. The fourth parameter is a documentation string describing
-what the parameter signifies. Finally, there are three optional parameters. Note
-that there are methods to define other types of parameters; ``add_boolean_parameter``
-could be especially useful.
+what the parameter signifies. Finally, there are three optional parameters. 
+``default_value`` is the value the parameter is set to by default.
+If ``is_vector == True``, the parameter is a vector of a fixed length. This
+length is defined as the number of parameters of the getters and setters
+(scalar parameters have only one parameter). 
+If ``must_set_before_get == True``, the parameter must be set before it can be returned. 
+In most cases, this can be False.
+
+
+Note that there are methods to define other types of parameters:
+
+=========================== ============================
+function                    purpose
+=========================== ============================
+add_boolean_parameter       the parameter is a boolean,
+                            instead of an integer/float.
+add_caching_parameter       the parameter is only set
+                            once ``commit_parameters`` is
+                            called.
+add_array_parameter         the parameter is an array;
+                            in contrast with a normal
+                            parameter with ``is_vector=True``,
+                            the getters and setters have
+                            only a single argument, which
+                            must be able to handle arrays.
+                            Between the setter and the name,
+                            an additional function must be
+                            passed that specifies the size
+                            of the array.
+=========================== ============================
+
+``add_alias_parameter`` is also available to add an alias to an existing parameter.
+It is of the following form: ``add_alias_parameter("alias_parameter", "original_parameter", 
+"parameter documentation")``.
+
 
 Parameters are accessed through the ``parameters`` property of the code object:
 

doc/tutorial/index.rst

@@ -15,6 +15,6 @@ Tutorials
    legacy_code
    plot
    grid_boundary
-
+   documenting