Previous Up Next

20  DEVELOPMENT NOTES

DE.10

20.1  PROGRAMMING GUIDELINES

The present document (User’s Manual) deals primarily with a detailed description of all the input commands of the EUROPLEXUS code, in the order in which they appear in a typical input file. It is meant to be an exhaustive reference for Users of the code, but it is not a tutorial.


Some short indications are given in this Section, which might be useful to EUROPLEXUS code developers (i.e. to programmers), in the form of simple programming guidelines. Developers are assumed to have access to the EUROPLEXUS Consortium web site, which contains among other things all the available technical documentation.


Only an overview is presented here for brevity. Reference is made to several reports and other documents, listed in the bibliography and available on-line on the Consortium web site, which contain all the details.

20.1.1  Programming Language

EUROPLEXUS is entirely written in the Fortran language. For historical reasons some parts of the code (the oldest ones) are still coded in Fortran 77 (F77). All new developments from 1999 onwards use the Fortran 90 (F90) language, mainly based upon F90 Modules.


A great effort of converting F77 parts to F90 is being performed, but the process is not yet complete. An example of successful conversion is the materials data structure, which has been completely ported to F90.

20.1.2  F77 Programming

An introduction to F77 programming style in EUROPLEXUS is given in reference [150].

20.1.3  F90 Programming

An introduction to F90 programming style and some tentative guidelines for the development of EUROPLEXUS are given in reference [175].

20.1.4  Code Profiling

A code profiler is not readily available under Windows. A simple mechanism is set up to profile selected parts of the code (in a platform-independent way) by using the standard system routine CPU_TIME, which returns the job’s CPU time in seconds.

This profiling cannot be totally automatic as e.g. under Linux, but it is is set up in such a way:

The mechanism is very simple. Assume we want to profile a routine SUB1. Then the following standard code is inserted at the beginning of the routine (before the first executable statement) and at the end of the routine (before the RETURN or the END SUBROUTINE):

  SUBROUTINE SUB1
  ...
  USE M_PROFILE
  ...
  CIF PROFILE
  * Profiling
        LOGICAL, SAVE ::  LPROF
        INTEGER, SAVE ::  IPROF
        REAL(4) :: TPROF1, TPROF2, TPROFD
        DATA LPROF, IPROF /.TRUE., 0/
        IF (LPROF) THEN
          CALL GET_PROFILE_INDEX ('SUB1', IPROF)
          LPROF = .FALSE.
        ENDIF
        CALL CPU_TIME (TPROF1)
  CENDIF

   ... routine body (executable statements)

  CIF PROFILE
        CALL CPU_TIME (TPROF2)
        TPROFD = TPROF2 - TPROF1
        CALL CUMULATE_PROF_TIME (IPROF, TPROFD)
  CENDIF
  END SUBROUTINE SUB1

Note that the two code portions to be inserted can be just copied (e.g. from LOOPELM.FF) and pasted as such. Only the name of the subroutine (SUB1) in the CALL GET_PROFILE_INDEX has to be changed.

To activate profiling of the routine, compile it with the PROFILE keyword activated for filtering. Under Windows the command is:

  epx_cmp -o -k PROFILE

Then link normally and run the code normally. At the end of the listing the profile table is printed, reporting the CPU time spent in each profiled portion of the code (both in absolute terms and in % of total CPU time), and the number of calls of each profiled routine.

The CIF PROFILE ... CENDIF code portions can be safely left in the routines, since they have no impact on normal code efficiency thanks to the standard EUROPLEXUS filtering mechanism.

Obviously, this type of profiling is not only limited to entire subroutines. The same mechanism can also be used to profile other code parts, e.g. a suspect DO loop. The name passed to GET_PROFILE_INDEX can be freely chosen by the user, it is not necessarily a subroutine name (maximum length is 32 characters, including any inter-word blanks).

Profiling instructions (filtered) will be gradually inserted in at least the most important routines of the code (CELEM, LOOPELM etc.) so that first-attempt profiling can become as simple es the following commands (under Windows):

  epx_modtree M_PROFILE    (search routines already containing M_PROFILE)
  epx_get_users            (copy all such routines in current directory)
  <possibly add some other routines for profiling>
  epx_cmp -o -k PROFILE    (compile all local routines for profiling)
  epx_lk -o                (link to produce a local executable epx.exe)
  epx_bench -e epx.exe ... (run tests and obtain profile)

Based on the results of this first-level profiling, other routines can then be added to the list for a refinement of profiling results.

The implementation uses a very small module M_PROFILE containing some very small static tables (no allocation / dealloction), with space for up to NPROFMAX (currently 100) routines to be profiled.

A permanent (unfiltered) profiling based upon the above mechanism has been added in the time loop routines: CALCUL for the normal case or TLOOPP for the case with spatial partitioning. Thus, by default the following main “blocks” of code are profiled:

This should give a first-level (and fully automatic) overview of where in the code the majority of CPU time is spent, for a given application. Then, refinement of the profiling can be performed if necessary by the technique explained above on the affected code portion.

20.2  PRECOMPILER KEYWORDS

DE.15

Several precompiler keywords are used before the compilation, shown in the table below. Concerning the versions, ’X’ indicates that it is used, ’(X)’ means that it is used in some cases and ’-’ that it is never used.


KeywordDescriptionVersions
  WinL64
  IspraCEA
CADNAVersion CADNA-(X)
CHECK_DATASALOME: check only syntax validity of epx file--
CYGWINWindows version with CYGWIN--
ER_LIGHT_VERSIONFiltering for the research light version-(X)
ER_VERSIONFiltering for the research version-(X)
EPX2XMLVersion EPX2ML DATA for Salome-(X)
FRANCAISOutput: French version, otherwise English version-X
GFORTRANGFORTRAN Compiler-(X)
KAAPINeed library KAAPI-X
MEDNeed library MED-X
MFFTNeed library MFFTXX
MFRONTNeed library MFRONT-(X)
MKLNeed library MKL (MKL is part of the Intel compiler)XX
MPIVersion MPI(X)X
NCOCONeed library NCOCOX(X)
OGLOpenGL (Windows)X-
ONLYF90Fortran 90 pur, no extension Fortran 2000, 2003, etc....-X
PETSCUse of PETSc (EDF)-(X)
PROD_VERSIONFiltering for the production version-(X)
PROFILEPerformance profile calculation--
QWINQuick Win--
SOFANeed library SOFA--
T_LINUXVersion OGL for Linux-(X)
UNIX32Not windows version-X
W32Windows 32 bit(X)-
W64Windows 64 bitX-
WINWindows (32 and 64 bit)X-
XLFXLF (IBM/AIX) compiler-X
 

Keywords for the manual


KeywordDescriptionVersions
  HTMLPDF
FIGURESIncluding the figuesXX
HEVEAHAVEA versionX-
LATEX1?  
PDFLATEXPDFLATEX version-X
SALOMESpecial treatment for SALOME menus--
TTHTTHZ-
 

DE.20

20.3  MANUAL CREATION

This documentation is produced starting from a LATEX source file that is continuously updated and maintained. A formatted version of the manual, such as the present one, can be obtained for on-line consulting either via PDF or via HTML.


A table of contents and an index can be found at the beginning and at the end of this documentation, respectively, and may help to rapidly retrieve information.

20.3.1  PAGE NUMBERING CONVENTIONS

Each page of the present manual contains information in both an header (at the page top) and a footer (at the page bottom).


The header contains in its middle part a ‘page identification’ used to identify each page or sequence of pages dealing with a specific topic. This is composed by a letter or group of letters, indicating a ‘section’ of the manual, and a number. The same information is also repeated in the left part of the footer. The number is not the actual page number (this is given in the right part of the footer, instead), since this is subject to frequent changes as text is added or reformatting is performed. Cross references in the text are generally done by referring to the page identification.


The numbers appearing in the page identification are not incremented by 1, but have larger increments (usually 10) in order to leave space for future pages.


The page header contains in its right part a date indicating when a certain page has been inserted or modified in the manual.


The date in the centre of the footer corresponds to the manual edition date.

DE.30

20.4  ACKNOWLEDGEMENTS, LICENSES

Several libraries are used in the EUROPLEXUS code.

20.4.1  lib_vtk_io

This library is used to write the vtk-files that are used in order to allow an output for ParaView. The library is written by Stefano Zaghi and can be find here:
https://github.com/szaghi/Lib_VTK_IO.

Copyright (c) 2014, Stefano Zaghi All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

20.4.2  Blas, Lapack

The packages can be obtained from http://www.netlib.org/blas and http://www.netlib.org/lapack.

Copyright (c) 1992-2007 The University of Tennessee. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer listed in this license in the documentation and/or other materials provided with the distribution.

- Neither the name of the copyright holders nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

20.4.3  OpenMPI

Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana University Research and Technology Corporation. All rights reserved.
Copyright (c) 2004-2010 The University of Tennessee and The University of Tennessee Research Foundation. All rights reserved.
Copyright (c) 2004-2010 High Performance Computing Center Stuttgart, University of Stuttgart. All rights reserved.
Copyright (c) 2004-2008 The Regents of the University of California. All rights reserved.
Copyright (c) 2006-2010 Los Alamos National Security, LLC. All rights reserved.
Copyright (c) 2006-2010 Cisco Systems, Inc. All rights reserved.
Copyright (c) 2006-2010 Voltaire, Inc. All rights reserved.
Copyright (c) 2006-2011 Sandia National Laboratories. All rights reserved.
Copyright (c) 2006-2010 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.
Copyright (c) 2006-2010 The University of Houston. All rights reserved.
Copyright (c) 2006-2009 Myricom, Inc. All rights reserved.
Copyright (c) 2007-2008 UT-Battelle, LLC. All rights reserved.
Copyright (c) 2007-2010 IBM Corporation. All rights reserved.
Copyright (c) 1998-2005 Forschungszentrum Juelich, Juelich Supercomputing Centre, Federal Republic of Germany
Copyright (c) 2005-2008 ZIH, TU Dresden, Federal Republic of Germany
Copyright (c) 2007 Evergrid, Inc. All rights reserved.
Copyright (c) 2008 Chelsio, Inc. All rights reserved.
Copyright (c) 2008-2009 Institut National de Recherche en Informatique. All rights reserved.
Copyright (c) 2007 Lawrence Livermore National Security, LLC. All rights reserved.
Copyright (c) 2007-2009 Mellanox Technologies. All rights reserved.
Copyright (c) 2006-2010 QLogic Corporation. All rights reserved.
Copyright (c) 2008-2010 Oak Ridge National Labs. All rights reserved.
Copyright (c) 2006-2010 Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2009 Bull SAS. All rights reserved.
Copyright (c) 2010 ARM ltd. All rights reserved.
Copyright (c) 2010-2011 Alex Brick . All rights reserved.
Copyright (c) 2012 The University of Wisconsin-La Crosse. All rights reserved.
Copyright (c) 2013-2014 Intel, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer listed in this license in the documentation and/or other materials provided with the distribution.

- Neither the name of the copyright holders nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

The copyright holders provide no reassurances that the source code provided does not infringe any patent, copyright, or any other intellectual property rights of third parties. The copyright holders disclaim any liability to any recipient for claims brought against recipient by any third party for infringement of that parties intellectual property rights.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

20.4.4  Glut

Copyright (c) Mark J. Kilgard, 1994, 1997. The programs are not in the public domain, but they are freely distributable without licensing fees. These programs are provided without guarantee or guarantee expressed or implied.

20.4.5  f90gl, f90glu, f90glut

The package can be taken from here http://math.nist.gov/f90gl/.

The research software provided on this web site (’software’) is provided by NIST as a public service. You may use, copy and distribute copies of the software in any medium, provided that you keep intact this entire notice. You may improve, modify and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the software.

The software is expressly provided ’as is.’ NIST makes no warranty of any kind, express, implied, in fact or arising by operation of law, including, without limitation, the implied warranty of merchantability, fitness for a particular purpose, non-infringement and data accuracy. NIST neither represents nor warrants that the operation of the software will be uninterrupted or error-free, or that any defects will be corrected. NIST does not warrant or make any representations regarding the use of the software or the results thereof, including but not limited to the correctness, accuracy, reliability, or usefulness of the software.

You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. The software was developed by NIST employees. NIST employee contributions are not subject to copyright protection within the United States.


Previous Up Next