Compiling and linking user-defined code

You can use your user-interface within a PALM-run by carrying out the following steps:

1. Copy the appropriate default (empty) user-interface files user_***.f90 to the folder that has been defined in the configuration file by variable user_source_path. The default for this folder is $HOME/palm/current_version/JOBS/$run_identifier/USER_CODE, so in case the run identifier is example:

      cd ~/palm/current_version
      mkdir -p JOBS/example/USER_CODE
      cp trunk/SOURCE/user_***.f90  JOBS/example/USER_CODE
   

   Attention: do not change the names of the user-interface files!

2. Modify the interface routines according to your needs.
   

3. Start a PALM run by entering

      palmrun -d example ...
   

   The files user_***.f90 will be automatically compiled as part of this run, before PALM is executed, and will replace PALM‘s respective default user-interface routines. The compiled binaries are put into a folder named SOURCES_FOR_RUN_$configuration_identifier_$run_identifier, where they replace the default binaries that have been created via palmbuild. The SOURCES_FOR_RUN folder is created in the directory defined by variable fast_io_catalog in the configuration file. It is newly created for each manual call of palmrun.
   
   

Since the run identifier is part of the user-interface's SOURCE path, you can use different interfaces for different runs at the same time. Just store the respective interface-files in sub-folders JOB/abcd/USER_CODE, JOBS/cdef/USER_CODE, etc. and call palmrun with option "-d abcd", "-d cdef", etc.

If you like to add additional routines which are not part of the default user-interface (see the list of available interface routines), you can a) append this routines to the default user-interface file user_additional_routines.f90 or b) create new files in your user-interface folder. These files must have names different from the default PALM source code files. In case of b), you must also copy the default Makefile into the user-interface folder, e.g.:

   cp trunk/SOURCE/Makefile  JOBS/example/USER_CODE

Edit the Makefile and add your new files and possible dependencies, following the standard "make"-rules.

How to avoid re-compilation of user-interfaces

It is important to know, that in general the modified user-interface files cannot be pre-compiled with palmbuild. This would not make sense because your user-interface may differ among your PALM runs, so you would need different MAKE_DEPOSITORIES depending on the run-identifier (option -d). Therefore, palmrun compiles the user-interface each time you call the script. Strictly speaking, palmrun internally calls palmbuild with special options, and palmbuild then compiles the user-interface and generates the SOURCES_FOR_RUN folder (see above).

In case you carry out a large number of test runs and don't want the user-interface to be compiled each time again (because it may take a lot of time, and you didn't change it), you can suppress compilation by adding palmrun option -V. Then, palmrun/palmbuild tries to re-use the compiled interface from the last call of palmrun with same configuration identifier and run identifier (given by options -h and -d), by re-using the respective SOURCES_FOR_RUN folder that has been generated by the previous run. Automatically generated calls of palmrun (restart runs in job chains) use the same method, so they do not need to compile the user-interface again.

For debugging user-defined code, see section Debugging?.