Merge branch 'master' of https://github.com/teuben/nemo

.github/workflows/ccpp.yml

@@ -37,7 +37,7 @@ jobs:
 
   build2:
 
-    runs-on: macos-12
+    runs-on: macos-13
 
     steps:
     - uses: actions/checkout@v1

VERSION

@@ -1 +1 @@
-4.4.4
+4.5.0

docs/examples/spectrum-fit.html

@@ -13,6 +13,11 @@ <H1> Spectrum Fit </H1>
     tabplot spectrum1fit.tab 1 3 -50 50  -1 5 line=1,1 ycoord=0  yapp=2/xs
   </pre>
 
+  <H2> raw spectrum </H2>
+  <img src=spectrum_1.png>
+  <H2> baseline subtracted spectrum </H2>
+    <img src=spectrum_2.png>
+
 <P>
 This page was last modified on
 <!--#config timefmt="%d-%h-%Y" -->

docs/install_nemo.sh

@@ -18,7 +18,7 @@
 #   opt=1 python=1                          14'00"
 #
 
-echo "install_nemo.sh:  Version 1.9 -- 19-feb-2024"
+echo "install_nemo.sh:  Version 1.10 -- 20-oct-2024"
 
  opt=0                                                # install some optional mknemos= packages
  nemo=nemo                                            # root directory where NEMO will be installed (. = here)
@@ -141,7 +141,7 @@ fi
 
 # pick a configure
 
-CC=gcc$v CXX=g++$v FC=gfortran$v ./configure $opt $with_yapp
+CC=gcc$v CXX=g++$v F77=gfortran$v ./configure $opt $with_yapp
 #./configure $opt --enable-debug --with-yapp=pgplot --with-pgplot-prefix=/usr/lib     # ok
 #./configure $opt --enable-debug --with-yapp=pgplot --with-pgplot-prefix=/usr/lib   --enable-pedantic
 #./configure $opt --enable-debug --with-yapp=pgplot

docs/requirements.txt

@@ -2,3 +2,6 @@ numpydoc>=0.9.1
 sphinx>=4.1.1
 sphinx-rtd-theme
 sphinx_inline_tabs
+# dysh
+sphinx-rtd-theme
+sphinxcontrib-mermaid

docs/source/codes.rst

@@ -20,6 +20,8 @@ that have a tighter connection to NEMO:
 
 .. include:: starlab.rst
 
+.. include:: falcon2.rst 
+
 .. include:: rebound.rst   
 
 .. include:: galpy.rst   

docs/source/falcon2.rst

@@ -0,0 +1,150 @@
+FALCON2
+-------
+
+
+The falcon V2 package is still under development for a public release. The main
+integrator is now called ``griffin``, replacing the older ``gyrfalcON`` from falcon V1.
+Although falcon V1 is distributed with NEMO, it is not maintained and may eventually
+succumb to software rot. Users should switch to using ``griffin``.
+
+A paper describing the ``griffin`` FMM code is in Dehnen (2014)
+
+.. warning::
+   Adding FALCON2 to NEMO will result in some programs that have duplicated names, e.g. **mkplummer**.
+
+
+Installation
+~~~~~~~~~~~~
+
+Hopefully soon we can use 
+
+.. code-block::
+
+   mknemo falcON2
+
+but unless you are a close collaborator, this will likely not be working.
+
+This type of install would place the package in ``$NEMO/local/falcon2``, the
+file ``INSTALL.md`` describes the installation procedure.
+
+
+
+Command Line Interface
+~~~~~~~~~~~~~~~~~~~~~~
+
+Although the CLI will look familiar to NEMO users, there are some salient differences.
+Some highlights:
+
+- the CLI is a set of ``key=val``, like in NEMO. If given in order, the ``key=`` portion can be
+  omitted, leaving just a series of values. This not recommended in scripts.
+- ``--help`` describes the keywords and some help, much like the ``help=h`` option in NEMO
+- ``help=1`` shows hidden CLI options (NEMO doesn't have hidden options)
+- ``debug=`` 
+
+
+
+
+Examples
+~~~~~~~~
+
+
+For details on a specific program, type
+
+.. code-block::
+
+   program --help
+
+
+- Create a Plummer sphere with 100 particlces
+
+.. code-block::
+
+   mkplummer p100.in 100
+
+- View the contents of this HDF5 dataset
+
+.. code-block::
+
+   dump p100.in
+
+- Convert falcon2 HDF5 files to NEMO snapshot, and review like the ``dump`` program
+
+.. code-block::
+
+   s2a p100.in  | tabcomment - - delete=t | tabtos - p100.bsf block1=m,pos,vel,skip nbody=100
+   tsf p100.bsf
+
+- Comparing performance of griffin in parallel (oneTBB) mode:
+
+.. code-block::
+
+   rm -f p10k.*
+   mkplummer p10k.in 10000 time=0
+   /usr/bin/time griffin p10k.in p10k.out step=1 tstop=10 eps=0.05 tau=2^-4
+   threads=0    98.41user 19.02system 0:24.23elapsed 484%CPU 
+   threads=1    21.19user  0.79system 0:22.03elapsed  99%CPU     
+   threads=2    24.06user  2.90system 0:15.05elapsed 179%CPU
+   threads=4    33.37user  4.73system 0:13.77elapsed 276%CPU  40.70user 5.90system 0:16.47elapsed 282%CPU 
+   threads=8    62.97user 11.25system 0:21.23elapsed 349%CPU
+           12   82.25user 14.55system 0:24.61elapsed 393%CPU
+           16   93.44user 16.78system 0:25.63elapsed 430%CPU
+           20   97.90user 18.67system 0:23.95elapsed 486%CPU
+   
+   
+- Comparing falcon1 with falcon2
+
+.. code-block::
+
+   #  some parameters
+   nbody=10
+   eps=0.05
+   kmax=8
+   tstop=1
+   #
+   rm -f p1.*
+   mkplummer p1.in $nbody time=0
+   griffin p1.in p1.out step=1 tstop=$tstop eps=$eps tau=2^-$kmax
+   # 8.7sec
+
+   s2a p1.in | tabcomment - - delete=t | tabtos - p1.bsf block1=m,pos,vel,skip nbody=$nbody
+   gyrfalcON p1.bsf p1.out2  step=1 tstop=$tstop eps=$eps kmax=$kmax 
+   # 0.6 sec
+
+   # comparing initials (notice p1.out does not contain times=0)
+   echo "=== Initial conditions ==="
+   s2a p1.in times=0 | tabcols - 2:7
+   snapprint p1.out2 times=0 format=%11.9e
+
+
+   # comparing final 
+   echo "=== Final snapshot ==="
+   s2a p1.out times=$tstop | tabcols - 2:7
+   snapprint p1.out2 times=$tstop format=%11.9e
+
+
+but griffin is more accurate and such a direct comparison may not be fair. In particular, is tau=2^-$kmax even fair?
+
+- Comparing X and Y
+
+
+Surprises
+~~~~~~~~~
+
+to be resolved
+
+- dump --help
+
+  does not show the help we usually see, but seems to think --help is a file
+
+
+- "griffin --help"
+
+  says: "please provide 'out', 'tau', 'eps'"
+  why complain, we didn't attempt to run.
+
+- mkplummer has a keyword 'q-ran', but itsn't it better to use q_ran, since that's
+  a more common one used in all falcon programs. keep it consistent.
+
+- mkplummer has a default time=1
+
+- ..

docs/source/iface.rst

@@ -163,13 +163,16 @@ results in something like:
         fill_circle=t frame= VERSION=1.3f
 
 
-As you see, ``snapplot`` happens to be a program
+Compare the VERSION= with your version, and it will likely be different.
+
+
+As you can see, ``snapplot`` happens to be a program
 with quite an extensive parameter list.
 Also note that ``help`` itself is not listed in the above list of program
 keywords because it is a **system keyword**
 (more on these later).
 
-There are a few *short-cut*
+There are a few *short-cuts*
 in this user interface worth mentioning 
 at this
 stage.  First of all, keywords don't have to be specified 
@@ -178,7 +181,7 @@ order, they will be associated by the appropriate keyword.
 The order of program keywords can be seen with
 the keyword ``help=``.
 The moment you deviate from
-this order, or leave gaps, all 
+this order, or skip keywords, all 
 values must be accompanied by their keywords, *i.e.* in
 the example
 
@@ -301,7 +304,7 @@ In summary, the system keywords are:
   Deprecated
 
 - **np=**
-  Number of processors (for OpenMP) to maximally use. Default is max.
+  Number of processors (e.g. for OpenMP) to maximally use. Default is the max.
 
 For a more detailed description of the system keywords and all their options
 see :ref:`aiface`.  The actual degree of implementation of the system
@@ -326,15 +329,8 @@ shells like ``tcsh`` and ``bash``
 can be used very efficiently in this mode. 
 In batch mode shell scripts, if used properly, can provide a very
 powerful method of running complex simulations.
-Other plug-compatible
-interfaces that are available are ``mirtool`` and ``miriad``,
-described in more detail in
-Appendix~\ref{s:mirtool} and \ref{s:miriad} There was also a
-Khoros (cantata, under khoros V1)
-interface (``http://www.khoral.com``) available, but this product is not
-open source anymore.
 Lastly, lets not forget scripting languages like python, perl and ruby. 
-Although the class UNIX (c)sh shell is very WYSIWYG, with a modest amount
+Although the classic UNIX (c)sh shell is very WYSIWYG, with a modest amount
 of investment the programmability of higher level scripts can give you
 a very powerful programming environment.
 
@@ -391,10 +387,14 @@ caveat, here are various help options:
     keyword descriptions and more vertical space.
 
     The special ``--help`` option is allowed for those with gnu fingers.
+    Using ``-h`` is a short-cut.
 
     The special ``--man`` option delivers the unix style man
     page (see next item).
 
+    The special ``--version`` option displays the current version.
+    Using ``-v`` is a short-cut.  
+
 - Unix manual pages
     for programs, functions, and file
     formats, all in good old UNIX tradition. All these
@@ -437,7 +437,8 @@ caveat, here are various help options:
     as well as advanced users, and at is being coverted to this RST
     manual, outdated.
 
-- This manual, in **reStructuredText** might be available in many different formats. html and pdf are the common ones.
+- The manual you are reading here,
+  in **reStructuredText** might be available in many different formats. html and pdf are the common ones.
 
 
 .. _aiface:

docs/source/progr.rst

@@ -24,24 +24,36 @@ We start by looking at the *Hello Nemo* program:
 
 .. code-block:: C
    
-	#include <nemo.h>                         /* standard (NEMO) definitions */
+	#include <nemo.h>                      /* 1. standard (NEMO) definitions */
 
-	string defv[] = {       /* standard keywords and default values and help */
+	string defv[] = {    /* 2. standard keywords and default values and help */
 	    "n=10\n                    Number of interations",           /* key1 */
 	    "VERSION=1.2\n             25-may-1992 PJT",                 /* key2 */
 	    NULL,               /* standard terminator of defv[] vector          */
 	};
 
-	string usage = "Example NEMO program 'hello'";        /* usage help text */
+	string usage = "Example NEMO program 'hello'";     /* 3. usage help text */
 
-	void nemo_main()                   /* standard start of any NEMO program */
+	void nemo_main()                /* 4. standard start of any NEMO program */
 	{
 	    int n = getiparam("n");                          /* get n            */
     
 	    printf("Hello NEMO!\n");                         /* do some work ... */
 	    if (n < 0)                                       /* deal with fatal  */
 	       error("n=%d is now allowed, need >0",n);      /* errors           */
 	}
+
+
+Although this looks like C, there are four odd looking ways a typical NEMO program
+is structured.
+
+1. An include file that captures NEMO definitions (such as string)
+2. A global string array defv/[] that defines the command line user interface
+3. A global string that captures a usage
+4. A global function nemo_main() that defines the starting point of the NEMO program
+
+The standard C main() is present in the NEMO library, with which each program
+is linked, but ensures the program is set up for the NEMO environment.
 
 
 
@@ -50,20 +62,25 @@ The NEMO Programming Environment
 
 The modifications necessary to your UNIX environment in order to
 access NEMO are extensively described elsewhere.  This not only
-applies to a user, but also to the application programmer.
+applies to a user, but also to developers.
 
 In summary, the essential changes to your environment consist of
 one simple additions to your local shell startup file
-or you can do it interactively in your shell (be it sh or csh like).
+or you can do it interactively in your shell, viz.
 
 .. code-block:: bash
 
       % source /opt/nemo/nemo_start.sh
-   or
-      % source /opt/nemo/nemo_start.csh
 
 where the location of NEMO=/opt/nemo is something that will likely
-be different for you.
+be different for you. This example is for bash-like shells, there
+is a similar file for csh, and there is also an option so use modules,
+such that a command like this will work:
+
+.. code-block:: bash
+
+      % module load nemo
+
 
 
 The NEMO Macro Packages