From 712ca374b0612b07a3ee8c8808797bc755883f3a Mon Sep 17 00:00:00 2001 From: elkogerville Date: Thu, 28 May 2026 16:36:50 +0200 Subject: [PATCH 1/9] def adding_example_code_tidymess in index.rst --- doc/tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 7be640b60a..2760f8a26d 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -16,4 +16,4 @@ Tutorials legacy_code plot grid_boundary - + adding_example_code_tidymess From 63e003a1b23cfa97a9c5412a9a88091cb7e23861 Mon Sep 17 00:00:00 2001 From: elkogerville Date: Thu, 28 May 2026 16:39:58 +0200 Subject: [PATCH 2/9] new documentation file about adding tidymess to amuse --- doc/tutorial/adding_example_code_tidymess.rst | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 doc/tutorial/adding_example_code_tidymess.rst diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst new file mode 100644 index 0000000000..43297b0b4a --- /dev/null +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -0,0 +1,66 @@ +.. _adding_example_code_tidymess: + +Adding a C++ N-Body Code to AMUSE +================================= + +In this tutorial, we will create an interface from scratch for the +TIdal DYnamics of Multi-body ExtraSolar Systems code, or ``TIDYMESS``, +written by Dr. Tjarda Boekholt and Dr. Alexandre Correia. This code +implements detailed tidal forces into an N-body code to track the deformation +of bodies. This community code has already been implemented into AMUSE so you +can follow along this tutorial. + +Getting Started +=============== + +This tutorial assumes you have a working amuse or amuse development build, +preferrably in seperated environment (virtualenv, venv or conda etc). +Please ensure that amuse is setup correctly, this can be verified by running the +``amusifier`` . + +.. code-block:: bash + + > amusifier --help + +Naming our project +~~~~~~~~~~~~~~~~~~ +Amuse naming conventions typically follows PascalCase, so we will name our project Tidymess. + +Creating the initial directory structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To start, we need to create the directory structure for ``Tidymess``, along with the +necessary files to build our interface. The fastest method to setup the directory is +by using the ``amusifier`` script with ``--mode=dir``. + +Since ``TIDYMESS`` is a native C++ code with no other dependencies, we will specify +``--type=c``, but the ``amusifier`` can also build the interface directory for +``f90`` and ``python`` codes. + +.. code-block:: bash + + > amusifier --type=c --mode=dir Tidymess + +Having run the ``amusifier``, we now have our new directory in ``amuse/src/amuse_tidymess``. +There should be all the required folders for building our interface, as well as a few code +stubs to expand upon. + +Building the code +================= +Before we start working on the interface, we should try and install and compile ``TIDYMESS`` +inside of ``AMUSE``. + +Defining dependencies +~~~~~~~~~~~~~~~~~~~~~ +The ``AMUSE`` build system needs to know what packages and libraries our project depends on. +Navigate to ``amuse_tidymess/packages/amuse_tidymess.amuse_deps``, which is where we define every +dependency we will need. By default it will look like: + +.. code-block:: text + + c c++ fortran java python cmake install download mpi openmp cuda opencl x11 opengl blas lapack gsl gmp mpfr fftw hdf5 netcdf4 + +Since ``TIDYMESS`` is a standalone C++ code, we can simplify our dependencies to: + +.. code-block:: text + + c c++ From e1cdab5242946a71a827a7d4e2340401517fd719 Mon Sep 17 00:00:00 2001 From: elkogerville Date: Fri, 29 May 2026 12:17:10 +0200 Subject: [PATCH 3/9] more docs on adding tidymess to amuse --- doc/tutorial/adding_example_code_tidymess.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index 43297b0b4a..1f4dfaabd6 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -59,8 +59,23 @@ dependency we will need. By default it will look like: c c++ fortran java python cmake install download mpi openmp cuda opencl x11 opengl blas lapack gsl gmp mpfr fftw hdf5 netcdf4 -Since ``TIDYMESS`` is a standalone C++ code, we can simplify our dependencies to: +Since ``TIDYMESS`` is a standalone C++ code, we can delete most of those and simplify our dependencies to: .. code-block:: text c c++ + +Setting up Autoconf +~~~~~~~~~~~~~~~~~~~ +The ``amuse_deps`` file we just created informs the ``AMUSE`` build system about whether or not our +package is buildable given the available compilers and libraries detected on your computer. We now need +to determine what compilers and libraries are on the system and how to use them. For this we will edit +the ``configure.ac`` file in ``amuse_tidymess/support/``. This file contains a set of macros which will +detect the tools and libraries needed to build our package. The template should contain all the macros +needed for our package, so its just a matter of deleting what we don't need. + +.. WARNING:: + + Make sure the the ``amuse_tidymess/support/shared/`` folder is a simlink to ``amuse/support/shared/`` + to ensure that there is no code duplication in the codebase, and that bug fixes are propagated to each + package automatically. From cc3f2ffbb8449331a6e0efa6857d9db9c0ff5f6d Mon Sep 17 00:00:00 2001 From: elkogerville Date: Fri, 29 May 2026 15:58:59 +0200 Subject: [PATCH 4/9] more sections on tidymess docs --- doc/tutorial/adding_example_code_tidymess.rst | 26 +++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index 1f4dfaabd6..af73f53be7 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -10,6 +10,12 @@ implements detailed tidal forces into an N-body code to track the deformation of bodies. This community code has already been implemented into AMUSE so you can follow along this tutorial. +.. NOTE:: + + In this guide, ``TIDYMESS`` refers to the standalone simulation package, + while ``Tidymess`` refers to the ``TIDYMESS`` package inside of ``AMUSE``. + + Getting Started =============== @@ -72,10 +78,26 @@ package is buildable given the available compilers and libraries detected on you to determine what compilers and libraries are on the system and how to use them. For this we will edit the ``configure.ac`` file in ``amuse_tidymess/support/``. This file contains a set of macros which will detect the tools and libraries needed to build our package. The template should contain all the macros -needed for our package, so its just a matter of deleting what we don't need. +needed for our package, so its just a matter of deleting what we don't need. Delete any comment prefaced +with ``#####``, but only after following the direction of the comment. + +Once ``configure.ac`` is setup correctly, we can edit ``config.mk.in``, and remove any unneeded variables +as well as any ``#####`` comment. This file is a template for ``config.mk``, which will contain a description +of all the compiler and library variables needed for our package. + +Once these files are cleaned up, run ``autoreconf`` to (re)create the ``configure`` script, then run +``./configure``. This will test the detection and check for errors. As a sanity check, run ``cat config.mk`` +and ensure that there are no ``@VARIABLE@`` symbols left! If there are, check that ``configure.ac`` and +``config.mk.in`` were setup correctly. .. WARNING:: Make sure the the ``amuse_tidymess/support/shared/`` folder is a simlink to ``amuse/support/shared/`` to ensure that there is no code duplication in the codebase, and that bug fixes are propagated to each - package automatically. + package automatically. This should be done automatically by the ``amusifier`` but can be a source of bugs + if not setup correctly. + +Setting up the Makefile +~~~~~~~~~~~~~~~~~~~~~~~ +With our build system detection working, we now need to download ``TIDYMESS`` into ``AMUSE``! +This is where the Makefiles come in. ``AMUSE`` packages typically have 2 Makefiles. From 4eb451ad76930e108e0aa83e97a7ec08777fc298 Mon Sep 17 00:00:00 2001 From: elkogerville Date: Mon, 1 Jun 2026 19:27:13 +0200 Subject: [PATCH 5/9] started section on creating tidymess interface --- doc/tutorial/adding_example_code_tidymess.rst | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index af73f53be7..5c73d4afec 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -101,3 +101,45 @@ Setting up the Makefile ~~~~~~~~~~~~~~~~~~~~~~~ With our build system detection working, we now need to download ``TIDYMESS`` into ``AMUSE``! This is where the Makefiles come in. ``AMUSE`` packages typically have 2 Makefiles. + + +Creating the Interfaces +======================= +With ``TIDYMESS`` compiled into ``AMUSE``, we can now begin the process of creating our interface! +The interface system allows community codes, which are all unique and depend on diverse libraries and +programming languages, to communicate with the ``AMUSE`` framework, which is native Python. ``AMUSE`` +interfaces define a number of interface functions, which provide a standardized way for ``AMUSE`` to +communicate with each community code. This way, the experience of using any ``AMUSE`` code is identical: +all codes can be evolved with the ``evolve_model`` method, particles are represented as +``amuse.datamodel.particles``, etc... The strength of ``AMUSE`` lies in its ability to prototype quickly: +If the user wants to see what solution a different code would give for the same calculation, all they have +to do is switch which code they are using, and the script most likely does not need to change. + +Therefore, our job when creating an interface is to map the community code functions to the ``AMUSE`` interface +functions. The amusifier already created all the files we need: the ``interface.py`` and the ``interface.cc``. + +Defining the Python interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``interface.py`` actually defines two classes: the high-level and low-level Python interfaces. The high-level +interface is what the user interacts with when using the community code. This defines the methods, parameters, +and properties of each community code, and defines how the ``amuse.datamodel.particles`` work within that code. +The ``amusifer`` generates a minimal code stub for the ``interface.py``, which is enough to get us started. +The process of defining our interface starts with figuring out what type of code we are adding to ``AMUSE``. +``AMUSE`` has a set of predefined Python interfaces we can use to build our interface from. + + ++----------------------------------+-------------------------------------------+ +| Interface: | Example codes: | ++----------------------------------+-------------------------------------------+ +| ``GravitationDynamicsInterface`` | N-body: Tidymess, Ph4, Huyano | ++----------------------------------+-------------------------------------------+ +| ``HydrodynamicsInterface`` | Hydrodynamical: Capreole | ++----------------------------------+-------------------------------------------+ +| ``MagnetoHydrodynamicsInterface``| MHD: Athena | ++----------------------------------+-------------------------------------------+ +| ``StellarEvolutionInterface`` | Stellar: MESA, EVtwin, SeBa | ++----------------------------------+-------------------------------------------+ + +These interfaces define many +of the required interface functions so that we don't have to. +In this case, ``TIDYMESS`` is a N-Body code, and therefore falls under the From b84528b6ab97e4db66da802ef67336827ecbcd09 Mon Sep 17 00:00:00 2001 From: elkogerville Date: Tue, 2 Jun 2026 16:09:04 +0200 Subject: [PATCH 6/9] typo fixes and improvments on adding tidymess example code --- doc/tutorial/adding_example_code_tidymess.rst | 53 ++++++++++++++++--- 1 file changed, 45 insertions(+), 8 deletions(-) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index 5c73d4afec..12171cc3a2 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -20,8 +20,8 @@ Getting Started =============== This tutorial assumes you have a working amuse or amuse development build, -preferrably in seperated environment (virtualenv, venv or conda etc). -Please ensure that amuse is setup correctly, this can be verified by running the +preferably in seperated environment (virtualenv, venv or conda etc). +Please ensure that amuse is set up correctly, this can be verified by running the ``amusifier`` . .. code-block:: bash @@ -30,7 +30,7 @@ Please ensure that amuse is setup correctly, this can be verified by running the Naming our project ~~~~~~~~~~~~~~~~~~ -Amuse naming conventions typically follows PascalCase, so we will name our project Tidymess. +PEP-8 naming conventions for classes follows PascalCase, so we will name our project Tidymess. Creating the initial directory structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -40,10 +40,11 @@ by using the ``amusifier`` script with ``--mode=dir``. Since ``TIDYMESS`` is a native C++ code with no other dependencies, we will specify ``--type=c``, but the ``amusifier`` can also build the interface directory for -``f90`` and ``python`` codes. +``f90`` and ``python`` codes. Make sure you run the ``amusifier`` in the ``amuse/src/`` directory. .. code-block:: bash + > cd amuse/src/ > amusifier --type=c --mode=dir Tidymess Having run the ``amusifier``, we now have our new directory in ``amuse/src/amuse_tidymess``. @@ -52,7 +53,7 @@ stubs to expand upon. Building the code ================= -Before we start working on the interface, we should try and install and compile ``TIDYMESS`` +Before we start working on the interface, we should try to install and compile ``TIDYMESS`` inside of ``AMUSE``. Defining dependencies @@ -69,7 +70,43 @@ Since ``TIDYMESS`` is a standalone C++ code, we can delete most of those and sim .. code-block:: text - c c++ + c++ + +To test that we did everything properly, we can run the ``./setup`` script from the root directory of ``AMUSE``:: + + > cd amuse/ + > ./setup + Checking for dependencies, one moment please... + + *** Configuration complete *** + Detected features: c c++ fortran python python-dev gmake cmake install download patch tar unzip gunzip bunzip2 unxz perl bison mpi openmp blas lapack gsl gmp mpfr fftw libz hdf5 netcdf4 qhull healpix-cxx + + ** Enabled packages ** + + Packages marked i) are currently installed. + + i) amuse-framework amuse-hop amuse-petar + amuse-aarsethzare amuse-huayno-openmp amuse-ph4 + amuse-adaptb amuse-huayno amuse-phantom + amuse-athena amuse-kepler amuse-phigrape + amuse-bhtree amuse-kepler-orbiters amuse-rebound + amuse-brutus amuse-krome amuse-sakura + amuse-bse amuse-mameclot amuse-seba + amuse-capreole amuse-mercury amuse-secularmultiple + amuse-evtwin amuse-mesa-r15140 amuse-sei + amuse-fastkick amuse-mesa-r2208 amuse-simplex + amuse-fi amuse-mi6 amuse-smalln + amuse-fractalcluster amuse-mikkola amuse-sphray + amuse-gadget2 amuse-mmams amuse-sse + amuse-galactics amuse-mobse amuse-symple + amuse-galaxia amuse-mocassin amuse-tidymess + amuse-halogen amuse-mosse amuse-tupan + amuse-hermite amuse-mpiamrvac amuse-twobody + amuse-hermite-grx amuse-nbody6xx amuse-vader + +We can see that the ``AMUSE`` framework is correctly installed, indicated by the ``i)`` symbol. We can +also see our package ``amuse-tidymess`` is listed meaning the ``AMUSE`` build system now knows of our project +and we are ready to move on! Setting up Autoconf ~~~~~~~~~~~~~~~~~~~ @@ -92,7 +129,7 @@ and ensure that there are no ``@VARIABLE@`` symbols left! If there are, check th .. WARNING:: - Make sure the the ``amuse_tidymess/support/shared/`` folder is a simlink to ``amuse/support/shared/`` + Make sure the the ``amuse_tidymess/support/shared/`` folder is a symlink to ``amuse/support/shared/`` to ensure that there is no code duplication in the codebase, and that bug fixes are propagated to each package automatically. This should be done automatically by the ``amusifier`` but can be a source of bugs if not setup correctly. @@ -131,7 +168,7 @@ The process of defining our interface starts with figuring out what type of code +----------------------------------+-------------------------------------------+ | Interface: | Example codes: | +----------------------------------+-------------------------------------------+ -| ``GravitationDynamicsInterface`` | N-body: Tidymess, Ph4, Huyano | +| ``GravitationDynamicsInterface`` | N-body: Tidymess, Ph4, Huayano | +----------------------------------+-------------------------------------------+ | ``HydrodynamicsInterface`` | Hydrodynamical: Capreole | +----------------------------------+-------------------------------------------+ From 7759a39b7d086f53dbbed450ac9fdb98bb4fd6fd Mon Sep 17 00:00:00 2001 From: elkogerville Date: Tue, 2 Jun 2026 16:16:33 +0200 Subject: [PATCH 7/9] more doc revisions --- doc/tutorial/adding_example_code_tidymess.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index 12171cc3a2..c9c4a31243 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -30,7 +30,7 @@ Please ensure that amuse is set up correctly, this can be verified by running th Naming our project ~~~~~~~~~~~~~~~~~~ -PEP-8 naming conventions for classes follows PascalCase, so we will name our project Tidymess. +PEP-8 naming conventions for classes follows PascalCase, so we will name our project ``Tidymess``. Creating the initial directory structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -72,10 +72,11 @@ Since ``TIDYMESS`` is a standalone C++ code, we can delete most of those and sim c++ -To test that we did everything properly, we can run the ``./setup`` script from the root directory of ``AMUSE``:: +To test that we did everything properly, we can run ``./setup`` from the top-level directory of ``AMUSE``:: > cd amuse/ > ./setup + Checking for dependencies, one moment please... *** Configuration complete *** @@ -110,9 +111,7 @@ and we are ready to move on! Setting up Autoconf ~~~~~~~~~~~~~~~~~~~ -The ``amuse_deps`` file we just created informs the ``AMUSE`` build system about whether or not our -package is buildable given the available compilers and libraries detected on your computer. We now need -to determine what compilers and libraries are on the system and how to use them. For this we will edit +We now need to determine what compilers and libraries are on the system and how to use them. For this we will edit the ``configure.ac`` file in ``amuse_tidymess/support/``. This file contains a set of macros which will detect the tools and libraries needed to build our package. The template should contain all the macros needed for our package, so its just a matter of deleting what we don't need. Delete any comment prefaced From 436762441a77e203d243eedf286cf704201b1a0a Mon Sep 17 00:00:00 2001 From: elkogerville Date: Tue, 2 Jun 2026 16:34:27 +0200 Subject: [PATCH 8/9] expanded configure section of adding tidymess docs --- doc/tutorial/adding_example_code_tidymess.rst | 32 +++++++++++-------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index c9c4a31243..affdd5a72f 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -115,11 +115,17 @@ We now need to determine what compilers and libraries are on the system and how the ``configure.ac`` file in ``amuse_tidymess/support/``. This file contains a set of macros which will detect the tools and libraries needed to build our package. The template should contain all the macros needed for our package, so its just a matter of deleting what we don't need. Delete any comment prefaced -with ``#####``, but only after following the direction of the comment. +with ``#####``, but only after following the direction of the comment. Since ``TIDYMESS`` is a native C++ code, +most of the optional macros can be deleted, especially the ones related to external libraries like ``CUDA``, +``MPI``, ``FFTW``, etc... The only library we will keep is ``AMUSE_LIB_STOPCOND()`` for enabling stopping +conditions in our project, as well as ``AMUSE_DOWNLOAD()`` and ``AC_CHECK_TOOL(TAR, tar)`` for dynamically +downloading ``TIDYMESS`` from github into our project when the user tries to install it (so we don't need to package +the source code directly into ``AMUSE``). Once ``configure.ac`` is setup correctly, we can edit ``config.mk.in``, and remove any unneeded variables as well as any ``#####`` comment. This file is a template for ``config.mk``, which will contain a description -of all the compiler and library variables needed for our package. +of all the compiler and library variables needed for our package. Just like ``configure.ac``, the only optional variables +we will keep are again related to the ``STOPCOND`` library and downloading our package. Once these files are cleaned up, run ``autoreconf`` to (re)create the ``configure`` script, then run ``./configure``. This will test the detection and check for errors. As a sanity check, run ``cat config.mk`` @@ -164,17 +170,17 @@ The process of defining our interface starts with figuring out what type of code ``AMUSE`` has a set of predefined Python interfaces we can use to build our interface from. -+----------------------------------+-------------------------------------------+ -| Interface: | Example codes: | -+----------------------------------+-------------------------------------------+ -| ``GravitationDynamicsInterface`` | N-body: Tidymess, Ph4, Huayano | -+----------------------------------+-------------------------------------------+ -| ``HydrodynamicsInterface`` | Hydrodynamical: Capreole | -+----------------------------------+-------------------------------------------+ -| ``MagnetoHydrodynamicsInterface``| MHD: Athena | -+----------------------------------+-------------------------------------------+ -| ``StellarEvolutionInterface`` | Stellar: MESA, EVtwin, SeBa | -+----------------------------------+-------------------------------------------+ ++-----------------------------------+-------------------------------------------+ +| Interface: | Example codes: | ++-----------------------------------+-------------------------------------------+ +| ``GravitationDynamicsInterface`` | N-body: Tidymess, Ph4, Huayano | ++-----------------------------------+-------------------------------------------+ +| ``HydrodynamicsInterface`` | Hydrodynamical: Capreole | ++-----------------------------------+-------------------------------------------+ +| ``MagnetoHydrodynamicsInterface`` | MHD: Athena | ++-----------------------------------+-------------------------------------------+ +| ``StellarEvolutionInterface`` | Stellar: MESA, EVtwin, SeBa | ++-----------------------------------+-------------------------------------------+ These interfaces define many of the required interface functions so that we don't have to. From 143162429645e468ff9cf2c3072487296da3f099 Mon Sep 17 00:00:00 2001 From: elkogerville Date: Tue, 2 Jun 2026 16:47:34 +0200 Subject: [PATCH 9/9] minor adjustment --- doc/tutorial/adding_example_code_tidymess.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial/adding_example_code_tidymess.rst b/doc/tutorial/adding_example_code_tidymess.rst index affdd5a72f..b2ba5a27d7 100644 --- a/doc/tutorial/adding_example_code_tidymess.rst +++ b/doc/tutorial/adding_example_code_tidymess.rst @@ -117,7 +117,7 @@ detect the tools and libraries needed to build our package. The template should needed for our package, so its just a matter of deleting what we don't need. Delete any comment prefaced with ``#####``, but only after following the direction of the comment. Since ``TIDYMESS`` is a native C++ code, most of the optional macros can be deleted, especially the ones related to external libraries like ``CUDA``, -``MPI``, ``FFTW``, etc... The only library we will keep is ``AMUSE_LIB_STOPCOND()`` for enabling stopping +``MPI``, ``FFTW``, etc... The only optional macros we will keep are ``AMUSE_LIB_STOPCOND()`` for enabling stopping conditions in our project, as well as ``AMUSE_DOWNLOAD()`` and ``AC_CHECK_TOOL(TAR, tar)`` for dynamically downloading ``TIDYMESS`` from github into our project when the user tries to install it (so we don't need to package the source code directly into ``AMUSE``).