HMD Mathematics Code
Numerical mathematics platform, Matlab alternative
Brought to you by:
racefortune
Menu
▾
▴
Tree [25dbc5] master / History
Read Me
--------------------------------------------------------------------------
README file for HMD for Computer Modeling
--------------------------------------------------------------------------
Last updated 3-19-2017, version 4.3.11
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
The build package looks for GNU Readline installed on your computer.
If it is found, then the interactive command-line capability will
be built into your program. If GNU Readline is not installed on
your computer, then you can still use HMD to execute .hmd scripts,
but there will be no interactive prompt--in other words, typing
"hmd -i" will cause hmd to exit immediately. If you want the
interactive prompt you must download and install GNU Readline, then
rebuild the HMD package. This package will almost always be already
be installed on your Linux distribution.
* LAPACK
Reguired for the matrix algebra
(LAPACK is now included in the package--you do not need to worry
about downloading and installing)
* Tcl/Tk (optional)
If you want to run the graphical user interface (hmd -j) you need
to have Tcl/Tk installed on your computer. If so, the ./configure
script will find it, and the Tcl/Tk interface will be compiled into
the program. The program executes some Tcl scripts which will be
located in the share path, usually /usr/local/share/hmd/tcl.
Any serious Linux/Unix distribution should have Tcl/Tk already
installed.
* BLT (optional)
You should not have to worry about this unless something goes wrong.
The BLT library is a subset of the Tcl/Tk functionality. A compiled
BLT library is provide and distributed into the share path, which
will usually be /usr/local/share/hmd, hence the libraries will be
found inside /usr/local/share/hmd/tcl/blt. This approach is yet
experimental (12-24-2016). If the BLT libraries do not run because
of an incompatibility with the version of Tcl/Tk you have on your
machine you will need to install and compile your own BLT package
and copy the libraries into the share path stated above.
Dec 2018: the BLT 2.5 source tree is distributed in the HMD source
tree under HMD_SOURCE/tcl/blt/blt2.5. You need to build this package
before running the HMD versions of ./configure, make, make install.
See the file README_hmd under HMD_SOURCE/tcl/blt/blt2.5.
* TkTable (optional)
You should not have to worry about this unless something goes wrong.
The TkTable library is a subset of the Tcl/Tk functionality. A compiled
TkTable library is provide and distributed into the share path, which
will usually be /usr/local/share/hmd, hence the libraries will be
found inside /usr/local/share/hmd/tcl/tktable. This approach is yet
experimental (12-24-2016). If the TkTable libraries do not run because
of an incompatibility with the version of Tcl/Tk you have on your
machine you will need to install and compile your own BLT package
and copy the libraries into the share path stated above.
Dec 2018: the TkTable 2.11 source tree is distributed in the HMD source
tree under HMD_SOURCE/tcl/tktable/tktable2.11. You need to build this
package before running the HMD versions of ./configure, make, make install.
See the file README_hmd under HMD_SOURCE/tcl/tktable/tktable2.11.
* ECL Embedded Common Lisp (optional)
If you use the graphical user interface the Lisp interpreter window
will be available. ECL is not a standard Linux/Unix package.
You must have already installed ECL on your computer. When you build
HMD, and ECL is alread installed, the HMD configure script will find
ECL and build the Lisp interface into the program. But you will not
be able to use it unless you have Tcl/Tk and the program is started
with "hmd -j -k".
The HMD interface to ECL assumes that you built ECL without unicode. To
see whether you have a conflict enter a simple floating point number
assignment into the Lisp interpreter console, say (setq x 1312.45) and
observe the console echo. If there is only one digit displayed, or if
the echo looks trashed then you compiled your ECL distribution with
unicode on. You could rebuild ECL with
./configure --enable-unicode=no --with-unicode-names=no
Or, if you feel you cannot live without unicode, edit the HMD source file
called eval_lisp_ecl.c. Put #define ECL_BUILD_WITH_UNICODE near the top
of the file.
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.
--------------------------------------------------------------------------
--------------------------------------------------------------------------
2. Building HMD
--------------------------------------------------------------------------
--------------------------------------------------------------------------
First, navigate under the HMD Mathematics source tree to the blt/blt2.5
directory and build BLT. See the file README_hmd under
HMD_SOURCE/tcl/blt/blt2.5.
Then, navigate under the HMD Mathematics source tree to the
tktable/tktable2.11 directory and build TkTable. See the file README_hmd
under HMD_SOURCE/tcl/tktable/tktable2.11
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.
--------------------------------------------------------------------------
--------------------------------------------------------------------------
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 <hmd_script_file_name>
where, of course, <hmd_script_file_name> must be replaced by the name of your
HMD script file.
How do you exit from interactive mode? Type exit.
The graphical user interface can be used if Tcl/Tk is on your machine.
The GUI is invoked when you start the program with
hmd -j
Possible errors that would occur trying to use the "-j" option:
tclGUI_Main returned -7
The Tcl/Tk script for displaying the GUI cannot find the share path. This
should not occur for a normal Linux install. We look for the share path
either in /usr/local/share/hmd or /usr/share/hmd. But if you are trying to
run from a non-standard location you need to manually set the share path on
the command line or with the .hmd_config file in the current directory. The
HMD share folder will contain a subdirectory called tcl. This will be a
subdirectory in the source tree that is automatically copied to the share
path for a normal installation. If you did not perform a normal installation
then whereever to have the HMD share files, say /home/hmd, you can use a
command line option
-s /home/hmd
or create a file called .hmd_config in the location where you're invoking
HMD, and put the share location in it, like
hmdsharepath = /home/hmd
See the section called FILES.
This would be a problem also for Windows users who want to run HMD from a
different folder than the installation folder. But in this case the file
would be called hmd_config.cfg.
The missing share path prblem could also cause a BLT not loaded error or
a TkTable not loaded error.
----------------------------------------------------------------------------
--------------------------------------------------------------------------
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.
----------------------------------------------------------------------------
----------------------------------------------------------------------------
8. FILES
----------------------------------------------------------------------------
----------------------------------------------------------------------------
Files generated and/or used by the HMD program for configuration or other
purposes.
.hmd_config
Contains configuration that apply only to the local session.
1. An alternative to the default "hmdsharepath" path. The default is
/usr/local/share/hmd
This can be overriden by the environment variable, HMDSHAREPATH,
which could then be overriden by the command line option, -s.
They can all be overriden by a setting in the local .hmd_config
for the hmdsharepath. Example,
hmdsharepath /home/share/hmd
2. An alternative path to the help file. This is a text file containing
all the help descriptions. The default path is
$HMDSHAREPATH/help/hmd_help.txt
which, for the default path, resolves to
/usr/local/share/hmd/help/hmd_help.txt
This can be overriden in the local .hmd_config file. Example,
help_path /home/myproj/myhelp.txt
.hmdtk
The .hmdtk file is a local session file for sessions using the Tcl/Tk
GUI (a session started with the -j option).
.histinterp
The command line history for the HMD command workspace when using the
Tcl/Tk GUI (a session started with the -j option).
.hmd_history
The command line history for the HMD command workspace when using the
text console (a session started with the -i option).
.histlisp
The command line history for the ECL common lisp command workspace when
using the Tcl/Tk GUI (a session started with the -j and -k option).
.eclout
A named pipe file in the local directory used for internal communication
between the ECL embedded stdout stream and the Tcl/Tk widget that hosts
the Lisp interpreter.
----------------------------------------------------------------------------
----------------------------------------------------------------------------
Alfred Steffens Jr.
apsteffe@netwood.net
