diff --git a/.github/workflows/ccpp.yml b/.github/workflows/ccpp.yml index d78b3725d..5cf909658 100644 --- a/.github/workflows/ccpp.yml +++ b/.github/workflows/ccpp.yml @@ -37,7 +37,7 @@ jobs: build2: - runs-on: macos-12 + runs-on: macos-13 steps: - uses: actions/checkout@v1 diff --git a/VERSION b/VERSION index cbe06cdbf..a84947d6f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.4.4 +4.5.0 diff --git a/docs/examples/spectrum-fit.html b/docs/examples/spectrum-fit.html index ac2e3a307..741aee28b 100755 --- a/docs/examples/spectrum-fit.html +++ b/docs/examples/spectrum-fit.html @@ -13,6 +13,11 @@

Spectrum Fit

tabplot spectrum1fit.tab 1 3 -50 50 -1 5 line=1,1 ycoord=0 yapp=2/xs +

raw spectrum

+ +

baseline subtracted spectrum

+ +

This page was last modified on diff --git a/docs/install_nemo.sh b/docs/install_nemo.sh index 071fe3178..a48a444ba 100755 --- a/docs/install_nemo.sh +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index e69e1df3c..b7ba3a4c8 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/codes.rst b/docs/source/codes.rst index 872200eae..fdc8b14b7 100644 --- a/docs/source/codes.rst +++ b/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 diff --git a/docs/source/falcon2.rst b/docs/source/falcon2.rst new file mode 100644 index 000000000..db21b8ebb --- /dev/null +++ b/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 + +- .. diff --git a/docs/source/iface.rst b/docs/source/iface.rst index 65fae831e..8d54da895 100644 --- a/docs/source/iface.rst +++ b/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: diff --git a/docs/source/progr.rst b/docs/source/progr.rst index f0f464a8d..ecded0afa 100644 --- a/docs/source/progr.rst +++ b/docs/source/progr.rst @@ -24,17 +24,17 @@ We start by looking at the *Hello Nemo* program: .. code-block:: C - #include /* standard (NEMO) definitions */ + #include /* 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 */ @@ -42,6 +42,18 @@ We start by looking at the *Hello Nemo* program: 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 diff --git a/docs/source/scripting.rst b/docs/source/scripting.rst index e12ad3737..ed727107e 100644 --- a/docs/source/scripting.rst +++ b/docs/source/scripting.rst @@ -1,14 +1,11 @@ Scripting --------- - -.. todo:: more scripting examples needed here - -We will focus on **bash** scripting here, basing comments -on the **mkmh97.sh** script. +We will focus on **bash** scripting here, for an example see the +**mkmh97.sh** script. A typical script will contain the following components -1. *hash-bang* the first line of the script, and optionally include nemo_functions.sh +1. *hash-bang* the first line of the script, and optionally include ``nemo_functions.sh`` where various convenience functions are maintained @@ -32,8 +29,9 @@ and make the script executable run=run1 # directory and run ID #> ENTRY nbody=1000 # number of bodies #> RADIO 1000,10000,100000,1000000 + eps=0.05 # softening #> SCALE 0:1:0.01 -and the parsing could be achieved as follows +and then parsing could be achieved as follows .. code-block:: bash @@ -42,7 +40,7 @@ and the parsing could be achieved as follows done 3. optionally, but highly recommended, some matching **--HELP** tags that can be retrieved using -a --help command line option +the --help command line option .. code-block:: bash @@ -77,3 +75,49 @@ a --help command line option 5. the body of the script, shell variables, nemopars variables etc. should be used where possible. + + + +Example: Extracting results from run directories +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A common workflow is to run a series of simulations and walking over a multi-dimensional parameter space. +This usually results into running each simulations in its own run-directory, plus storing +parameters and possibly resulting values in a parameter file for later extraction. The directory name +could even contain the value of these parameters as well. Several common strategies have been seen in +the wild, we list three: + +.. code-block:: + + # 1. simply enumerated (e.g id=001,002,003,....) parameters stored inside + run_${id} + + # 2. linear list of directories, parameters stored inside + run_${a}_${b}_${c} + + # 3. hierarchical directories, parameters stored inside + run/$a/$b/$c + +Although easier to visually identify the values of the parameters in 2. and 3., they don't scale very +well if a new parameter is introduced. In the first case a simple lookup table can be created using +``nemopars``, thus making it easier to find which parameters are used in while run directory. Here's +an example: + +.. code-block:: + + nemopars id,a,b,c run_*/nemopars.rc > run.pars + + + +Summary +~~~~~~~ + +Summarizing, here are the recommended methods to maintain and extract NEMO variables. + +1. **nemopars**: extract parameters from a bash-style rc file (python should also be able to use it) + +2. **nemovar**: get and set NEMOVAR variables + +3. **show_vars**: alias via nemo_functions.sh + + diff --git a/docs/whatsnew.html b/docs/whatsnew.html index decf3c9ea..4714e666f 100644 --- a/docs/whatsnew.html +++ b/docs/whatsnew.html @@ -21,13 +21,23 @@

What's New in NEMO


--> + +

4.5.0: in git

+ +
-

4.4.3/4.4.4: in git

+

4.4.3/4.4.4/4.4.5 (a.k.a. Malta Release)