Editing NUFEB code
==================

By the end of the tutorial, you will have edited some existing NUFEB source code to
produce a simple additional output. You will then run the build system
to update the NUFEB executable with the edited code.

The goal is to produce a trivial change in the codebase to understand the basics
of how NUFEB is built. This is the first step in understanding how to extend the NUFEB codebase to do things like add a new metabolism or interaction.

Overview
--------

NUFEB is written in C++ and uses a Unix-style build environment. You should be
somewhat comfortable with the command line, the ``gcc`` compiler, the ``make`` build utility, and ``git``.


.. note::
   NUFEB has also been built with ``clang`` and ``cmake``.

Because NUFEB is technically a module within the ``LAMMPS`` codebase, the build
process is slightly more complicated than one might expect.

First, there are two apparent codebases, and they may appear at first glance to have many repeated files.
They can be found under ``./lammps_stable_23June2022/src'`` and ``./src``.

There's a lot of reasons for this, but the end result is that you should edit code within the ``./src`` tree, copy ``./src`` to ``./lammps_stable_23June2022``, and then run ``make`` from within ``./lammps_stable_23June2022/src'``.

.. warning::
   This tutorial assumes you've successfully run the install script and NUFEB already works on your machine.
   The state of those source trees is setup by the install script, if you get errors (such as a makefile not being found) this is the fist thing to check.

Printing a notice when a new microbe is formed
----------------------------------------------

To produce an immediate visual confirmation that the code was edited and compiled correctly, we're going to do something you should not really do in practice.  We're going to print a line directly to the screen alongside the usual output generated by a run.

We'd also like to edit existing code so that we don't get bogged down with details on adding classes or new NUFEB modules.

First, let's insulate the codebase from these changes by working in a new branch, using git.
From the top directory of the repository, type ``git checkout -b tutorial_edit_code``.

Now, let's edit ``./src/NUFEB/fix_divide_coccus.cpp`` so that we celebrate the birthday of every new cell.
At the very end of the function ``void FixDivideCoccus::compute()``, alter the code to include the highlighted ``printf`` call.

.. code-block:: cpp
   :emphasize-lines:  6

        for (int m = 0; m < modify->nfix; m++)
            modify->fix[m]->update_arrays(i, j);

        delete[] coord;

        printf("Happy birthday to cell %d\n", j);
        }
      }
    }
    bigint nblocal = atom->nlocal;

Next, we need to copy the edited files to the build tree.
From the top directory of the repository: ``cp ./src/NUFEB/fix_divide_coccus.cpp ./lammps_stable_23June2022/src/NUFEB/fix_divide_coccus.cpp``

Now, go to the build tree: ``cd ./lammps_stable_23June2022/src``

To make the build system happy, we need to first tell it we're using NUFEB: ``make yes-nufeb``

Finally, we can build the new executable: ``make -j4 mpi``

This will produce the file ``./lammps_stable_23June2022/src/lmp_mpi``.  You may wish to move and rename it to the top-level directory, much as the installer script does: ``mv ./lammps_stable_23June2022/srcs/lmp_mpi ./nufeb_mpi``