MNRSIM README OVERVIEW ====================== Index to readme Documents: _readme.txt This document _readme_modules.txt Map to Modules _readme_labwindows.txt Some notes about LabWindows Overview -------- MNRSIM is a project originally conceived by Dr. Wm. Garland. The purpose of the project is to provide a visual and interactive model of the McMaster Reactor which runs faster than real time. The code for this project is based on two programs originally written for DOS, FLUX.C and CELL.C. This pair of programs solved the neutron diffusion equation in 2-D for 1-4 energy groups. Based on this a user interface and several other modules were added in 2003-2004, by D. Gilbert under the LabWindows Compiler versions 6.0.0. The project is meant to be on-going. File Structure -------------- The MNRSIM file package has a series of subdirectories each contain groups of special purpose files which are related to the project, they will be sumarized here: \ Source code is stored in root \cfg\ Configuration Files \cvibuild.mnrsim\ LabWindows Build Director \images\ Pictures & graphic development dir \orig\ Original Cell & Flux programs \pcx\ .pcx files for grid representation Summary of root directory (\) file types: The root directory of the zip package contains all of the source code for the project as well as the readme files. Any data input or output files ought to be stored in the configuration directory. .c .h Standard C source files .txt text documents like this one _cbf.c C source files which are predominantly call back functions .uir User Interface Resource files, these are generated by the LabWindows interface editor mnrsim.cws LabWindows project file mnrsim.prj LabWindows project file mnrsim.exe mnrsim executable, requires other files indent.exe code formatting program Summary of configuration directory (\cfg\) file types: The cfg directory contains a sequence of subdirectories, one for each saved configuration of the simulation. There is always a default directory, and there may be many others. Within each configuration directory there are several types of files: pipe.net The pipe network configuration 1energy.grp Energy group definitions for the cell module 2energy.grp 3energy.grp 4energy.grp cell.cel Defines mixtures of individual core cell types cell.ini Cell initialization file, no longer used cell.out output from the cell module, no longer used flux.inp input file for the flux module, no longer used flux.out output from the flux module, no longer used mat4grp.mat materials group input library g_state_1.dat variable state snapshots g_state_2.dat there can be lots and lots of them. g_state_3.dat g_state_4.dat ... panel_ccfg.cfg Panel state snapshots panel_cell.cfg there should be one for every window panel_core.cfg panel_ctrl.cfg ... Summary of labwindows directory (\cvibuild.mnrsim\) file types: This directory contains files built by LabWindows as part of the compilation process. I believe they are the individual object files built from each of the .c sources files. In any case they aren't needed once the program has been built, and can't be edited. Summary of images directory (\images\) file types: A few graphics have been drawn specifically for MNRSIM. This directory holds the original .fig files which can be edited by xfig (a UNIX based program). Generally this is a good place to leave partial or scratch work related to graphics. Summary of original files directory (\orig\) file types: MNRSIM was developed first as a graphical user interface to the smaller FLUX.C and CELL.C programs. They can be compiled independantly and run on their own. They are included for reference. Summary of pcx directory (\pcx\) file types: The pcx directory contains a collection of images which are used to represent the individual cells in the core display module. These files are loaded at runtime by MNRSIM. Code Structure -------------- Several code conventions have been established, it is hoped that new contributors will continue to follow these conventions and that they will find them helpful. Every function should have a comment banner outlined with "---" and "*" to make it easily identifiable. MNRSIM is built as a collection of modules. In C, files are used to collect together groups of related functions. Every function in a file uses its filename as the function name prefix. So in the flux.c file there is a function called flux_main(), which is the entry point for the principle method of this module. This convention makes code much easier to read, telling the programmer which file to look at to find a particular function simply based on its name. common.h, is the global header file which identifies the exported functions for each of the modules. Many modules only export some of their functions, the others are used internally. common.h is a good starting point for a new programmer to start investigating the code structure. LabWindows needs a collection of Call Back Functions in order for the user interface to be able to communicate with the physics program. Many files have "_cbf" as part of their names to indicate that they collect together groups of call back functions. While indenting may seem trivial, a carefully indented program is much more readable, and therefore much easier to maintain than one which is not carefully indented. Included in the directory is an automatic indentation program called "indent.exe". You can use this program to automajically fix the indentation of your files. To use this program enter the mnrsim directory and type: indent -kr -i 4 -nut *.c *.h Shared Variables ---------------- Global variables are avoided for a variety of reasons. In MNRSIM a special convention called "shared" variables is used. To access a shared variable a function calls shared_access(). Before a function exits it must release a shared variable by calling shared_release(). To create a new shared variable, edit the file called share.h. While the use of these primitives may at first glance seem to be a nuisance, several things should be remembered. #1 Global variables are bad programming practice and simply dangerous to use. Shared variables are checked and kept in order by the shared variable module. #2 Dr. Garland originally conceived of a distributed simulation environment, the shared variable primitives could be extended to facilitate a networked version of the program. #3 Shared variables help programmers to collaborate by making it 100% explicit which structures a function operates on. Using global variables instead of shared variables would force programmers to read entire sections of source code just to see what data structures were being operated on. #4 Shared variables flag unusual data access patterns which will help programmers to debug potentially complicated cross references. Global variables are used for panel handles. These were not changed to shared variables partly to maintain consistency with the LabWindows examples. These variables are also READ ONLY, and specific to the user interface.