Changes between Version 10 and Version 11 of doc/app/userint/comp

Timestamp:

Sep 7, 2018 9:40:51 AM (6 years ago)

Author:

raasch

Comment:

--

doc/app/userint/comp

@@ -2 +2 @@
 [[TracNav(doc/userint/toc)]]
 
-Users can add their own (modified) user-interface to a PALM-run by carrying out the following steps:\\\\
-   1. Copy the appropriate default (empty) user-interface files {{{user_***.f90}}} to a directory of your choice, e.g.:
+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 USER_CODE/example
-cp trunk/SOURCE/user_***.f90  USER_CODE/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 filenames! '''
+      '''Attention: do not change the names of the user-interface files! '''
 
-   2. Set an additional path in the configuration file .mrun.config to allow mrun to find and include these files:
+   2. Modify the interface routines according to your needs.\\
+
+   3. Start a PALM run by entering
 {{{
-%add_source_path   $base_directory/USER_CODE/$fname
+   palmrun -d example ...
 }}}
-      The default configuration file ({{{trunk/SCRIPTS/.mrun.config.default}}}) already includes this setting.\\
-   3. Modify the interface routines according to your needs.\\
-   4. Start a PALM run by executing
+      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 that is defined by variable {{{bla}}} in the configuration file. \\\\
+
+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 [wiki:doc/app/userint/int 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.:
 {{{
-mrun -d example ...
+   cp trunk/SOURCE/Makefile  JOBS/example/USER_CODE
 }}}
-      The files {{{user_***.f90}}} will be automatically compiled within the job and will replace the respective {{{PALM}}}‘s default user-interface routines.\\\\
+Edit the {{{Makefile}}} and add your new files and possible dependencies, following the standard "make"-rules.\\\\
 
-The above method with including {{{$fname}}} in the additional source path allows using different user interfaces for different runs at the same time. Just store the respective interface-files in subdirectories {{{USER_CODE/abcd}}}, {{{USER_CODE/cdef}}}, etc. and start '''mrun''' with option "{{{-d abcd}}}", "{{{-d cdef}}}", etc. \\\\
-If the user wants to add additional routines, he/she can a) put them into the default user-interface file {{{user_additional_routines.f90}}} or b) can create new files in the additional source directory. These files must have names different from the default {{{PALM}}} source code files. In case of b), the user must also copy the default makefile into the additional source directory:
-{{{
-cp trunk/SOURCE/Makefile  USER_CODE/example
-}}}
-The makefile must be modified appropriately following the "make"-rules in order to allow the new files to be compiled.\\\\
-'''The modified user-interface files cannot be pre-compiled by using mbuild! '''\\\\
-While programming user-defined code, errors are frequently made. For possible ways of error tracing, see [../../intdbg Debugging]. 
+It is important to know, that in general '''the modified user-interface files cannot be pre-compiled.''' with {{{palmbuild}}}. \\\\
 
-In case you are calling MPI functions or external functions from your user code, you might get error messages during the namelist file check, which is performed before your job is started. These errors will not occur during your model run, so you might skip the parameter file check in this case. The better option, however, is to exclude these calls from this check. In order to achieve this, can set the preprocessor directive {{{__check}}} wherever needed. 
+For debugging user-defined code, see section [../../intdbg Debugging]. 
 
-'''Example:'''
-{{{
-#if ! defined ( __check )
-CALL MPI_ALLREDUCE(...)
-#endif
-}}}