Package: collresolve
collresolveis a library designed to provide collision analysis and handling for N-body codes.The library has interfaces for the following languages:C/C++FortranPythonInstallationC/C++/FortranThe installation of the C/C++/Fortran library using the standard./configure,makeandmake installcommands.The repository does not provide theconfigurescript. If installing directly from the repository, the file must be created first. The easiest way to do this is executingautoreconf --installcommand which will create theconfigurescript and its dependencies. This command requires theGNU autoconftool. In this situation, the commands to execute are:autoreconf --install
./configure
make
make installAs for other packages, you may want to execute./configure --helpto see which options are available and tune that command to your needs, e.g. by changing the location where the library will be installed using the--prefix=PATHoption.LinkingIf the library has been installed in a non-standard part, then the paths to the header files and library object files must be provided to the compiler and linker calls. Hereafter, we assume that the base location of the library isPREFIX, which is the value of the--prefixargument to./configurecall.The public interface of the library for the C/C++ languages is provided in thecollresolve.hfile. In case the path must be provided, then the argument-IPREFIX/includemust be added to the compiler commands of files that make use ofcollresolve.h.To use the library, the argument-lcollresolveis to be provided to the linking command. In case the library is in a non-standard directory, the path can be provided using-LPREFIX/libargument.The Fortran interface is tailored to use with themercurypackage.PythonFrom a checkout of the repository, the Python module can be easily built and installed by the executing the following commands:python setup.py build
python setup.py installIn case the library is to be installed for the current user only, then the--userargument can be provided to theinstallcommand.This will put the Python module in a location where is it readily available. No further action is needed.UsageTo use most of the library, a configuration object must be created and set first. The configuration object contains essential parameters for the calls, such as the collision model to determine the outcome of collisions and the unit system in use. The object must not be accessed directly, but the functionscollresolve_conf_*should be used instead to alter its state.PythonAn example of usage of the library is provided in theexample.pyfile.MercuryTo use the library with themercury, the following modifications to the code of the latter are needed. When compiling the code, the additional flags described above to link the executable to the library are required.In themce_collsubroutine, near the end, in lieu of the partc
c Do the collision (inelastic merger)
      call mce_merg (jcen,i,j,nbod,nbig,m,xh,vh,s,stat,elost,
     %         nsetup)the code should be changed to something likeif (opt(2).eq.2 .and. i.gt.1 .and. j.gt.1) then
        model = 4
        nres = 2

        regime = collresolve_resolve(model, m(i) / K2, m(j) / K2,
     %     rphys(i), rphys(j), xh(:,i), xh(:,j), vh(:,i), vh(:,j), nres,
     %     mres, rres, pres, vres)

        if (regime .lt. 0) then
          ! An error occurred
          ! Do not do anything.
        else if (mres(1) .lt. 1.d-3 / (1047.d0 * 317.8d0)) then
          stat(i) = -2
          stat(j) = -2
          xh(:,j) = -xh(:,j)
          vh(:,j) = -vh(:,j)
        else if (mres(2) .lt. 1.d-3 / (1047.d0 * 317.8d0)) then
          m(i) = mres(1) * K2
          rphys(i) = rres(1)
          xh(:,i) = pres(:,1)
          vh(:,i) = vres(:,1)
          stat(j) = -2
          xh(:,j) = -xh(:,j)
          vh(:,j) = -vh(:,j)
        else
          m(i) = mres(1) * K2
          m(j) = mres(2) * K2
          rphys(i) = rres(1)
          rphys(j) = rres(2)
          xh(:,i) = pres(:,1)
          xh(:,j) = pres(:,2)
          vh(:,i) = vres(:,1)
          vh(:,j) = vres(:,2)
        end if
      else
c
c Do the collision (inelastic merger)
        call mce_merg (jcen,i,j,nbod,nbig,m,xh,vh,s,stat,elost,
     %         nsetup)
      end ifwith the following new variables at the beginning of the subroutinereal*8 mres(3),rres(3),pres(3,3),vres(3,3)
      integer nres,model,regime,collresolve_resolveThere are a few items to be noted with the above code:The library is only called when the flag about using the "fragmentation" mode in the parameters file is enabled. This allows to easily perform comparison run with mercury's standard merging algorithm with having to re-compile the code.The value of themodelvariable should be adjusted to which model the library is to use to resolve the collisions. The possible values are given in thecollresolve_modelenummeration incollresolve.h. The value provided in this code snippet,4, tells the library to use Cambioni et al. (2019) model.It implements a minimum mass cutoff for the remnants, with a value to 1/1000 of an Earth mass (the factor 1047 * 317.8 being the conversion to solar mass that Mercury uses as the mass unit).While the above codes sets the correct radii on return, these will be ignored in a standard version of themercurypackage. In effect, this will assume a constant density for each body. In case the model 4 (Cambioni et al. 2019) is used, a further modification is needed so that the bodies have a consistent radius with the bodies that were used to generate the model. To achieve this, the code setting the physical radius inmce_initshould be changed fromrphys(j)=hill(j)/a(j)*(temp/rho(j))**THIRDtorphys(j) = collresolve_radius(4, m(j) / K2)while addingreal*8 collresolve_radiusin the definitions of that subroutine. This will make mercury use the library's mass-radius relation  for all bodies (both at the beginning of the simulation and after a collision), except for the central body. In effect, this makes thedparameter in the input file useless.LicenseThe library is licensed under version 2.0 of the Apache License, see theLICENSEfile for the full terms and conditions.CitationsIf you use this library in a scientific work that lead to publication, we would like you to acknowledge the following article:Emsenhuber, A., Cambioni S., Asphaug, E., Gabriel, T. S. J., Schwartz, S. R., and Furfaro, R. (2020). Realistic On-the-fly Outcomes of Planetary Collisions. II. Bringing Machine Learning to N-body Simulations.The Astrophysical Journal, 891(1), 6.doi:10.3847/1538-4357/ab6de5bib:2020ApJ...891....6EIf you use theLS2012model, you should also cite:Leinhardt, Z. M. and Stewart, S. T. (2012). Collisions between Gravity-dominated Bodies. I. Outcome Regimes and Scaling Laws.The Astrophysical Journal, 745(1), 79.doi:10.1088/0004-637X/745/1/79bib:2012ApJ...745...79LIf you use theSL2012model, you should also cite the same publication as forLS2012, and:Stewart, S. T. and Leinhardt, Z. M. (2012). Collisions between Gravity-dominated Bodies. II. The Diversity of Impact Outcomes during the End Stage of Planet Formation.The Astrophysical Journal, 751(1), 32.doi:10.1088/0004-637X/751/1/32bib:2012ApJ...751...32SGenda, H., Kokubo, E., and Ida, S. (2012). Merging Criteria for Giant Impacts of Protoplanets.The Astrophysical Journal, 744(2), 137.doi:10.1088/0004-637X/744/2/137bib:2012ApJ...744..137GIf you use theC2019model, you should also cite:Cambioni, S., Asphaug, E., Emsenhuber, A., Gabriel, T. S. J., Furfaro, R., and Schwartz, S. R. (2019). Realistic On-the-fly Outcomes of Planetary Collisions: Machine Learning Applied to Simulations of Giant Impacts.The Astrophysical Journal, 875(1), 40. doi:10.3847/1538-4357/ab0e8abib:2019ApJ...875...40C