The Structure of DarkStar

Directory Structure Modular Layout Module Map Modules Description Customization Advanced Configuration

DarkStar is intended to be not only one particular kind of stellar evolution program, but a driver package for a variety of problems, even outside the scope of Astrophysics. Therefore, it has been constructed to give maximum flexibility to the user. This is achieved by a modular layout of the package, and a systematic directory structure together with management tools which handle different versions of one problem or even different problems easily.

The basic idea is that the user wants to work with a package, test changes, and has different versions of particular routines for different purposes. He may also have other closely related problems which differs only in a small set of routines. An example would be a stellar evolution package where there is a main set of working routines which are used for production runs, a set of routines with different microphysics, and a reduced set of equations for computation of, e.g., polytropes for test purposes. These routines share a common set of drivers and output subroutines, numerical solvers and so on.

DarkStar consists of two file management scripts and a set of Fortran 90 modules for different purposes, bundled with sample driver routines into an exemplary stellar structure package. The scripts and the modules are also separately usable for other purposes. They are based on widely spread and freely available, modern and standard Unix software and therefore are platform independent.

All DarkStar modules adapt themselves to the actual sizes of the problem. This enables,e.g., adaptive as well as multigrid approaches to the set of equations. The core numerical modules provide a Newton-Raphson solver for local problems with an arbitrary discretization bandwidth, a variety of boundary forms, and an automatic Jacobi matrix constructor. A Gauss elimination matrix solver for block-band matrices of arbitrary bandwidth backs up this package. Because the user is relieved from the tedious computations of Jacobian derivatives, he is encouraged to experiment freely with the equations, hopefully enhancing creativity and productivity.

The Directory Structure

In DarkStar, all these different problems and versions are managed by one Makefile and the corresponding dependency generator Make_Depp with user definable parts in Makefile.inc, and are distributed in a clearly arranged hierarchical directory structure. The "core" routines which are common to all versions or problems are collected in source, all version- or problem-dependent source files have their modified pendants in source_<v>;, where <v> is any number or string. A particular version is correctly compiled by typing

make <v>

(just typing make compiles the first version directory found, or only source, if no version directory exists). To be platform independent, make must be the GNU-Make program (version >= 3.70, often installed as /usr/local/bin/make or gmake).

The version dependent files are identified by just being in one of the source_<v> directories, that means, files of the same name in the corresponding location in source are ignored. With this technique the different versions can have different version-dependent files. Additionally/alternatively, the source files can be specified by subset selection. By default, all files present in source and source_<v> are considered for compilation.

The same applies to files containing F90 modules or include files, which reside in the modules or includes directories below in the corresponding source directory (include files can also be placed into further subdirectories in the includes directories or in other subdirectories instead of includes). Each of these files can reference modules or include files also from the corresponding other slot (references between different version files are senseless here). Therefore, seemingly version independent files can have indirect version dependencies by, e.g., including a version-dependent module to specify array sizes or the like. The dependency generator keeps track of all the complicated inter-dependencies of the two slots when recompiling to another version.

Library archive files and precompiled library module files are supported, they reside in an extra directory library_F90 and are expected to be up to date. The best way to include libraries from outside the working directory is a link in library_F90 to these.

All compiler output files (.o objects files and .mod,.M module information files) as well as the resulting executable is placed inside an automatically created directory hierarchy objects, objects_<v>, which resembles the structure of the corresponding source hierarchy and relieves the user from being annoyed by garbage files polluting the working directory. The executable file is placed into the directory OS. Make_Depp/Makefile themselves produce two files which are hidden from view, the dependency file .DarkStar.dep and an empty version time stamp file, .Version_<v>. These files should not be edited or deleted.

For customization of all the directory names, see below (note: Any changes in Makefile or Make_Depp force recompilation of all files).

The Module Concept

The modularity of the source code is accomplished by using the module concept of Fortran 90 . Functionally related subroutines on the same code level are grouped together in modules with definite interfaces and take care of their data structures themselves. So the programmer only has to present the relevant entities to a subprogram, internals (e.g., workspace arrays) are completely hidden from the interface. The possibility to allocate arrays dynamically enables dynamic adaption to the actual sizes of the problem and even changes of these sizes (e.g., for adaptive meshes, multigrid methods) within runtime.

The modules themselves are only wrapper files which include the relevant source files and define the data structures common to all module routines. Therefore, the user not only can change methods by using other modules, but is free to change specific codes inside the module by just including another source file (which, of course, has to respect the interface and data conventions of that module).

A module is also usable as an entity from any other driver program independently and can be exchanged in favour for other methods. Detailed information is available via a clickable map

Customization

All directory and output names are configurable from within the Makefile.inc (which is included into Makefile, Make_Depp is called and inherits the configuration from Makefile). The variables in Makefile.inc are assigned as follows (all pathes are relative to the main working directory, unless stated otherwise) :

Variable	Meaning	Default
`SOURCE_FILES`	Variable which the user can set to select a subset of the version independent source filenames (without directory and suffix, and except module source and include files). The main program file should be placed at the end.	<none = all>
`SOURCE_V_FILES`	Variable which the user can set to select a subset of the version dependent source filenames (without directory and suffix, and except module source and include files). The main program file should be placed at the end.	<none = all>
`COMP`	The f90 compiler brand (DEC, SUN, ABS, NAG, NEC, EPC, PGI ...). Used to configure include and module pathes, module name translation characteristics. Currently only the seven compilers above have been tested, and SUN, EPC and ABSoft need special handling. To configure for any other compiler, if necessary, see below. Caution: Case sensitive !
`F90C`	The Fortran 90 compiler command.
`OPTIONS`	The compiler options desired. The user may not place any include directives (`-I...`) here. The options are vendor specific, but not set automatically !
`LINK_OPTS`	The linker options desired.
`SRC`	The prefix name of the source slots: `$(SRC), $(SRC)_$V`, where `$V` is the variable for the version *<v>* (set automatically).	*source*
`MOD`	The name of the directories where F90 module sources in the source directories and the .mod or .M output files in the objects directories reside, relative to the corresponding source or objects slot.	*modules*
`INC`	The name of the directories where include sources in the source directories reside, relative to the corresponding source directory. Further include directories have to be located inside these ones.	*includes*
`OBJD`	Prefix of the directories where the output objects files shall go. These are organized analogously to the source slots and are generated automatically: `$(OBD), $OBD_$V`.	*objects*
`LIB, LIBV`	Module library files are constructed from $LIB and $LIBV as follows: $LIB=A[X] B[Y] and $LIBV=n m accesses Libraries A/$(OS)_n/libX.a and B/$(OS)_m/libY.a These libraries are assumed to be up to date.
`MLIBD`	created module library file (gmake <v> Library) is $(MLIBD)/$(OS)_<v>/lib$(MAIN).a
`EXCD`	Name of the directory of the executable file.	OS
`MAIN`	Name of the executable file inside the `$(EXD)` directory. This name is also used for the hidden dependency file, `.$(MAIN).dep`, which Make_Depp generates and which is included into the Makefile.	*Main*
`VERB`	Switch if verbose output from Make_Depp is desired (set to `-v`).	...

Advanced Configuration

Very rarely, further changes are necessary. One of these rare occasions could be a failure with a compiler not tested before. The main difficulties can arise from the different handling of module files. The suffix of the module information files differ (.mod,.M), and some compilers don't translate module names to lowercase for the module information files (e.g., SUN). Also the option for paths to look for module files can vary (-I...,-M...). Therefore, a section of the Makefile, identifiable by the initial line ifeq ($(COMP),...) is devoted to set these varying options.

The following variables may be changed to what is appropriate for the specific compiler:

Variable	Meaning	Default
`FFLAGS`	The complete list of Fortran 90 compiler flags. If the search path option for module information files is not `-I...`, then ADD (with +=) the correct search path options to `FFLAGS`, as already done for SUN and ABSoft. Changes here are also necessary if another compiler (e.g., F77) is used. The added pathes must be `$(OMV),$(OMV),$(RLIB)` (see next).	*...*

The following variables from the Makefile should not be changed, but are documented (in order of appearance) for further understanding of what's going on there:

Variable	Meaning	Default
`DEP`	The name of the hidden dependency file generated by Make_Depp and included into the Makefile. The definitions there get valid in the next recursive call of make.	*.DarkStar.dep*
`ECHO`	A command string for echoing a separating line.	*/bin/echo '==...'*
`VS`	The list of all version dependent source directories `source_<v>`.	*...*
`VERSIONS`	The list of all versions derived from `$(VS)`.	*...*
`V`	The version variable, set to whatever `<v>` currently is. Defaults to the first `<v>` found in the first call, reset in the next recursive make. Is 1 if only `source` is found.	1
`VFIL`	The version timestamp file prefix, file name is `$(VFIL)_$V`.	*.Version*
`LR`	The library archive filename stem, lib$(LR).a .	*...*
`LIBC`	The compiler library option string.	*-L$(RLIB) -l$(LR)*
`LIBR`	The full library name	*$(RLIB)/$(LIBF)*
`EXC`	The executable file.	*$(EXD)/$(MAIN)*
`SRV`	The version dependent source path.	*$(SRC)_$V*
`SIN`	The version independent include path.	*$(SRC)/$(INC)*
`SIV`	The version dependent include path.	*$(SRV)/$(INC)*
`SMD`	The version independent module path.	*$(SRC)/$(MOD)*
`SMV`	The version dependent module path.	*$(SRV)/$(MOD)*
`OBV`	The version dependent objects path.	*$(OBD)_$V*
`OMD`	The version independent module objects path.	*$(OBD)/$(MOD)*
`OMV`	The version dependent module objects path.	*$(OBV)/$(MOD)*
`MAKL`	The list: Makefile, Make_Depp. Used for recompiling when one of these files is changed.	*$(MAK) $(MAKD)*
`SRCL`	The list of all source files in the version independent `source` directory.	*...*
`SRCLIST`	`$(SRCL)` without directories and suffixes.	*...*
`SRC_USER`	The list of all source files in the version dependent `source_<v>` directory.	*...*
`SRCUSER`	`$(SRC_USER)` without directories and suffixes.	*...*
`SOURCE`	The user source list with all files in `$(SRCUSER)` filtered out.	*...*
`SOURCES`	The new complete user source list with all directories and suffixes.	*...*
`OBJECTS`	The complete object list with all directories and suffixes.	*...*

Here is a list of all targets in Makefile for reference:

Target	Meaning
`.SUFFIXES:`	Gmake special: delete list of suffix rules.
`.PHONY:`	Gmake special: all targets which are not real files.
`.DELETE ON ERROR:`	Gmake special: delete files created in a command that failed.
`NIL:`	First default entry, generates version 1
`$(VERSIONS):`	Version targets, only create directories, manage version file and call make with target $Va again.
`$Va:`	Recursive version target, call Make_Depp and set version, then call make with target `$(EXC)` again.
`$(EXC):`	The executable file target. Depends on version time stamp file, objects and library.
`$(OBD)/%.o:`	The version independent objects file target. Depends on version independent sources. Other dependencies are resolved via the included dependency file.
`$(OBV)/%.o:`	The version dependent objects file target. Depends on version dependent sources. Other dependencies are resolved via the included dependency file.
`$(VFIL)_$V`	The version time stamp file target. Update if Makefile/_Depp changed.
`$(DEP)`	The dependency file target. Create empty dummy file if not existent.
`CLEANUP`	Say make CLEANUP if strange errors occur, possibly resulting from prematurely terminated makes, compiler mixing or timing errors. This will delete all object, dependency and version files, giving a clean directory for rebuild.

The Make_Depp dependency generator should never be changed.

Home

last update 16. June 2007, U.Grabowski