-------------------------------------------------------------------------- README file for HMD -------------------------------------------------------------------------- ----------------------------------------------------------------------- Copyright 2002--2005 Alfred Steffens Jr. ----------------------------------------------------------------------- ----------------------------------------------------------------------- Copying Permission: Hmd is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. Hmd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Hmd (see file called "COPYING"); if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ------------------------------------------------------------------------ Contents --------- 1. Required Packages 2. Building HMD 3. Installing HMD 4. Getting Stated 5. Capability 6. Known bugs -------------------------------------------------------------------------- -------------------------------------------------------------------------- Introduction -------------------------------------------------------------------------- -------------------------------------------------------------------------- This source distribution was created with the GNU autotoolset. Building and installing this software is performed with the standard GNU "tarball" procedure of ./configure make make install Note that there are some required arguments that must be passed to ./configure (see below). The default installation path (resulting from "make install") is /usr/local. It is recommended that you keep the source distribution on your hard drive after the installation, although it is not required. If you keep the source distribution you will have the examples, and you will be able to uninstall the software at any time using "make uninstall". A good place for the distribution might be /usr/local/src. When the source tarball is unpacked the subdirectory hmd-x.x.x is automatically created, where x.x.x is the version number. -------------------------------------------------------------------------- -------------------------------------------------------------------------- 1. Required Packages -------------------------------------------------------------------------- -------------------------------------------------------------------------- * GNU ReadLine Provides command line text editing in interactive mode * LAPACK Reguired for the matrix algebra (LAPACK is now included in the package) * vis5d (optional) Needed to use the vis5d+ display program ( use ./configure --enable-vis5d=yes ) GNU READLINE ------------ HMD requires the READLINE package for the interactive console prompt. This package should be installed on most Linux distributions, but I don't know for sure which distributions have it. I know for sure that Slackware comes with READLINE already installed. If your distribution doesn't have it, then you need to download it from the GNU site and build/install it on your machine. LAPACK -- package for linear algebra ------------------------------------ As of version 3.1.0 (7/30/2005) the LAPACK source files are included in the HMD source distribution, so you don't need to download and install this package separately anymore (but information about how this would be done is retained at the bottom of this file for reference). GMSH ---- HMD is a model solver. So where are the neat wire-frame 3D images I wanted to see using a computer modeling tool? HMD uses another program for this. It's called GMSH. It is available from www.geuz.org/gmsh and can be downloaded for free. GMSH is used as a standalone program, not a library, so you don't have to worry about building it. Just download it and install it. You create a mesh file with GMSH. This file will have a file extension .msh. This file is what HMD needs to complete its finite element model. The GMSH mesh file name is specified as an HMD script command. Vis5D ----- HMD requires the Vis5D library for building its data translator for Vis5D, DAT2VIS5D. Vis5D is a graphical display program used in atmospheric science. You can find out more about Vis5d+ at the web page: http://vis5d.sourceforge.net/ -------------------------------------------------------------------------- -------------------------------------------------------------------------- 2. Building HMD -------------------------------------------------------------------------- -------------------------------------------------------------------------- After you have verified that the GNU Readline and Termcap libraries are installed, you can build and install the HMD package. I recommend copying the source distribution tarball file into /usr/local/src. Unpacking the distribution file will automatically create a subdirectory for HMD and put the project files there. Unpack the "tar ball" with the following commands: gzip -d hmd-x.x.x.tar.gz tar xvf hmd-x.x.x.tar or just tar zxvf hmd-x.x.x.tar.gz For the newer BZIP2'd distributions (.bz2 extension), use bzip2 -d hmd-x.x.x.tar.bz2 tar xvf hmd-x.x.x.tar Note that the "x.x.x" in hmd-x.x.x.tar.gz means the version number. Note that it doesn't matter whether the file extension is .tar.gz or .tgz. Change directory to the hmd-x.x.x directory. Build the project with the following commands: ./configure Now run make This will build hmd, intp, and other utility programs all at once. Optional tools: * dat2vis5d This tool will convert HMD output data into a format that vis5d can read. If you want this you will need to download the libvid5d libraries from the vid5d site and install them into /usr/local/lib. Then when you build HMD, use --enable-vis5d=yes when you run ./configure . -------------------------------------------------------------------------- -------------------------------------------------------------------------- 3. Installing HMD -------------------------------------------------------------------------- -------------------------------------------------------------------------- You don't have to do a formal "install" step to run HMD if you don't want to. The formal install step, which uses the standard GNU software installation scripts, will copy the HMD executable programs into your /usr/local/bin directory (where all users on you system can use HMD). If you want to install the package into the standard GNU file locations (should be /usr/local/bin), then type the following command: make install Otherwise, you can just cp the HMD executable file, hmd*, to whatever directory you want and use it there. After you have installed HMD (ONLY AFTER YOU INSTALL), you can run make clean to remove all the temporary files. -------------------------------------------------------------------------- -------------------------------------------------------------------------- 4. Uninstalling HMD -------------------------------------------------------------------------- -------------------------------------------------------------------------- When it's time to uninstall HMD you can use make uninstall Make sure that you keep the uninstall scripts from the package directory so that you can uninstall later. The safest way to do this is just leave the source code in /usr/local/src (where I assume you built HMD) and after install- ation is complete run make clean to get rid of the temporary files in the source directory. Then, when you want to uninstall HMD, change directory to the source directory and run "make uninstall". -------------------------------------------------------------------------- -------------------------------------------------------------------------- 5. Getting Started -------------------------------------------------------------------------- -------------------------------------------------------------------------- If you ran "make install", then the HMD programs will be in /usr/local/bin which should already be in your PATH. You may then run HMD from any directory. If you didn't run "make install", then you will need to cp the executables into the directory where you are working. Type hmd -V and the program should run, displaying the version number. Running a model --------------- Hmd reads and executes script files. For example, if we want to run the script file called "fe1.hmd" we would type the following command at the command line: hmd -f fe1.hmd Try it with example #1 ----------------------- To try example #1, change directory to a "work" directory. Copy the following files from the HMD examples directory (in the source package) to your work directory: fe1.hmd fe1.msh Note that I already created the mesh file, fe1.msh, for you. You could have created it your self by running GMSH with the input file fe1.geo to produce fe1.msh. Notice that you need at least two files: the HMD command script and the mesh file. Now execute the program: hmd -f fe1.hmd That's all it needs. You should get an output file called "fe1.dat", which is an ascii text file that will have 5 columns in the following order: 1. The node number corresponding to the data value. 2. The data value. 3. The x coordinate for that node. 4. The y coordinate for that node. 5. The z coordinate for that node. There will also be an output file called "fe1.inp". This is a file ready to be read into the GMV graphical viewer. Interactive Mode ----------------- You can run HMD interactively (like using Scilab or Matlab) with a variable workspace by starting HMD with the following command: hmd -i From interactive mode, you can run an HMD script by typing source where, of course, must be replaced by the name of your HMD script file. How do you exit from interactive mode? Type exit. ---------------------------------------------------------------------------- -------------------------------------------------------------------------- 5. CAPABILITY ---------------------------------------------------------------------------- -------------------------------------------------------------------------- 5/14/2003 A. Steffens Jr. ---------------------------------------------------------------------------- ---------------------------------------------------------------------------- In terms of the maximum size of model you can build with HMD. Maximum number of nodes on a PC with 512 Mb RAM: Model Type standard packed band-packed ------------------------------------------------------------------------- Poisson ? ? 16850 Eigenmodes 5120 12282 ------------------------------------------------------------------------- ---------------------------------------------------------------------------- -------------------------------------------------------------------------- 6. (Known) Bugs: ---------------------------------------------------------------------------- -------------------------------------------------------------------------- The SPARSPAK routine 1WD fails trying the create a band matrix with a mesh created on a toroidal geometry. ---------------------------------------------------------------------------- -------------------------------------------------------------------------- 7. LAPACK -- package for linear algebra ---------------------------------------------------------------------------- -------------------------------------------------------------------------- This is a well-known linear algebra package freely available at http://www.netlib.org/lapack It was written an debugged by mathematicians E. Anderson Z. Bai C. Bischof S. Blackford J. Demmel J Dongarra J. DuCroz A. Greenbaum S. Hammarling A. McKenny D. Sorensen LAPACK is used in Matlab, as well as other matrix algebra software programs such as Scilab and ALGAE. HMD now comes with the LAPACK files included, so the following section can be skipped. -------------------------------------------------------------------------- (obsolete as of 7/30/2005, I leave it here for reference) -------------------------------------------------------------------------- HMD requires the LAPACK (Linear Algebra) library. You must go to the LAPACK webpage and download the file lapack.tgz. It is free. But you must build it on your computer before you can build HMD. So, download http://www.netlib.org/lapack/lapack.tgz into the directory of your choice, say, /home/LAPACK. Now perform the following steps: L-1. gzip -d lapack.tgz L-2. tar xvf lapack.tar The following build commands assume that you are using Linux. If you are using some other flavor of Unix (or Cygwin on MS Windows) then consult the LAPACK documentation. At present I haven't ported HMD to any other platform (although this should all work on Cygwin). L-3. cp make.inc make.inc.orig L-4. cp install/make.inc.LINUX make.inc L-5. make Note: the make command is supposed to build and test everything. In my experience there will be a minor problem with the BLAS library not being built. If this happens you can run the make command again in the BLAS subdirectory. Check that you now have the two library files lapack_LINUX.a blas_LINUX.a If the file blas_LINUX.a is missing, then change directory to ./BLAS/SRC and run make again. Now you can move these two library files into a library directory of your choosing, let's say LAPACKLIBS. You will need to remember this directory path and the names of the two libraries when you build HMD. -------------------------------------------------------------------------- Change directory to the hmd-x.x.x directory. Build the project with the following commands: ./configure --enable-lapackpath=fullpath --enable-blaspath=fullpath Where "fullpath" in the ./configure command is the full path, including the file name, to the library file. In the section above, we placed the LAPACK libraries in a directory called LAPACKLIBS. So, for example, the above ./configure command would be run as follows: ./configure --enable-lapackpath=/LAPACKLIBS/lapack_LINUX.a --enable-blaspath=/LAPACKLIBS/blas_LINUX.a You MUST use the --enable-lapackpath and --enable-blaspath arguments to the ./configure command above. This tells the HMD makefiles where to find the LAPACK libraries. -------------------------------------------------------------------------- (end obsolete section) -------------------------------------------------------------------------- Alfred Steffens Jr. apsteffe@netwood.net http://www.lumanmagnum.net/physics/heldeneng/