Initial import of MiniXyce from Mantevo v1.0 release website

ref/README

@@ -0,0 +1,141 @@
+
+miniXyce circuit/network simulation mini-application
+
+--------------------------------------
+Contents of this README file:
+1. miniXyce overview
+2. miniXyce versions
+3. building miniXyce
+4. running miniXyce
+5. generating test circuits
+6. understanding the results
+--------------------------------------
+
+--------------------------------------
+1. miniXyce overview
+
+At this time, miniXyce is a simple linear circuit simulator with a 
+basic parser that performs transient analysis on any circuit with
+resistors (R), inductors (L), capacitors (C), and voltage/current 
+sources.  The parser incorporated into this version of miniXyce is a
+single pass parser, where the netlist is expected to be flat 
+(no hierarchy via subcircuits is allowed). Simulating the system of 
+DAEs generates a nonsymmetric linear problem, which is solved using 
+un-preconditioned GMRES. The time integration method used in miniXyce 
+is backward Euler with a constant time-step.  The simulator outputs
+all the solution variables at each time step in a 'prn' file.
+
+The development of the first version of miniXyce resulted in something
+closer to a compact application than a miniapp since more focus was put 
+on the simulator returning the correct answer, than modeling performance 
+characteristics of interest. Further analysis of Xyce has called out 
+particular performance issues in each of the three phases of circuit
+simulation:  parsing, device evaluation/loading, and the solution of linear
+equations.  These issues will inspire enhancements to, and a second version 
+of, miniXyce. 
+
+Finally, miniXyce compares the computed solution against gold standard output
+from Xyce for a couple test circuits found in the 'tests' directory.
+
+--------------------------------------
+2. miniXyce versions:
+- miniXyce_ref:
+     reference version: self-contained, includes serial and MPI-parallel
+     parallelism is optional, it can be built without MPI usage.
+
+-------------------
+3. Building miniXyce:
+
+ The default case is: cd into the 'miniXyce_ref' directory and type 'make'.
+ That will build the MPI-parallel miniXyce code assuming you have the
+ mpi-compiler-wrappers mpicxx in your path.
+
+ If successful, that will create an executable called miniXyce.x.
+
+Special builds can be done for things like:
+- gnu compilers (g++), no MPI
+  type 'make -f Makefile.gnu.serial'
+- Intel compilers (icpc), no MPI
+  type 'make -f Makefile.intel.serial'
+
+If the default makefile isn't correct for your system, copy and edit and
+use a 'make -f' command similar to the above cases.
+
+Note 1:
+  'make' calls the script 'generate_info_header' to generate miniXyce_info.hpp
+  with platform and build information. If that script fails for some reason and 
+  doesn't produce a valid miniXyce_info.hpp header, you can still build miniXyce by 
+  typing
+  'make MINIXYCE_INFO=0'.
+
+-------------------
+4. Running miniXyce:
+
+ miniXyce can be run like this:
+   % <mpi-run-command> miniXyce.x <options>
+
+ Description of command line options:
+
+  -c, --circuit {filename}: specifies the netlist to be simulated.
+  -ti, --tstart, --t_start {double value}: specifies start time of transient simulation
+  -tf, -- tstop, --t_stop {double value}: specifies stop time of transient simulation
+  -h, --tstep, --t_step {double value}: specifies the length of each transient simulation time step
+  -tol, --tolerance {double value}: specifies the GMRES tolerance
+  -k, --restart {double value}: tells GMRES how often to restart
+  -i, --init, --init_cond, --initcond, --x0 {vector of length (num_nodes + num_voltage_sources + num_inductors)}: 
+      specifies the initial condition for the simulation. If it is not specified, then a DC operating point initial condition is assumed.
+  -pf, --paramsfile, --params_file {filename}: specifies a file from which additional simulation parameters are to be obtained.
+  --prev : this flag tells the simulator to use whatever parameter values it used last time (for those parameters that have not been specifies on the command line)
+
+ miniXyce examples:
+
+  Ex 1: Run a simulation of circuit tests/cir1.net on 3 processors, using t_start = 1e-6 and other parameters taken from the file params.txt
+
+   mpirun -np 3 miniXyce.x --circuit tests/cir1.net --t_start 1e-6 --pf params.txt
+
+  Ex 2: Repeat the above simulation, but this time with 4 processors
+
+   mpirun -np 4 miniXyce.x --prev
+
+  Ex 3: Simulate the circuit cir4.net on 2 processors with default parameters
+
+   mpirun -np 2 miniXyce.x -c tests/cir4.net
+
+  Ex 4: Repeat the above simulation, but this time use an initial condition [2 3]
+
+   mpirun -np 2 miniXyce.x --prev --init 2 3
+
+  Note: The initial condition is *not* saved in the last_used_params.txt file. Only the rest of the parameters are saved. 
+        So if you use --prev without specifying anything else, a DC operating point initial condition will be computed.
+-----------------
+5. Generating test circuits:
+
+The test circuits provided in the 'tests' directory (cir1.net, cir2.net, cir3.net, and cir4.net) can run on, at most, 4 MPI processes.
+To make it easier to generate netlists for RC and RLC Ladders, there are 2 perl scripts RC_Ladder.pl and RLC_Ladder.pl in the 'tests' 
+directory. You can use them as follows:
+
+perl RC_Ladder.pl <number of RC Ladder stages you want> ><circuit name>.net
+perl RLC_Ladder.pl <number of RLC Ladder stages you want> ><circuit name>.net
+
+Example: perl RC_Ladder.pl 5 >cir6.net
+
+This allows the user to generate arbitrarily large linear circuits to test miniXyce.
+
+-----------------
+6. Understanding the results
+
+After running miniXyce, you will be left with a text file named <ckt_name>_tran_results.prn. There will only be one, regardless of the number of processors.
+
+The first line of this file is of the form:
+
+TIME state_variable_name_1 state_variable_name_2 ... state_variable_name_k
+
+Each subsequent line in each of these files gives values of the form:
+
+time value1 value2 ... valuek
+
+where value1 ... valuek are all the components of the solution vector x. 
+In addition, each line of the text file will contain two more attributes corresponding to the number of gmres iterations and restarts respectively.
+
+Matlab can be used to plot the data in this file using the very basic plot_tran_sim_results.m, which can be found in the 'utils' directory.
+

ref/common/YAML_Doc.cpp

@@ -0,0 +1,74 @@
+#include <ctime>
+#include <cstdlib>
+#include <ctime>
+#include <vector>
+#include <iostream>
+#include <fstream>
+#include <sstream>
+#ifdef REDSTORM
+#include <time.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#endif
+#include "YAML_Doc.hpp"
+using namespace std;
+
+//set the microapp_name and version which will become part of the YAML doc.
+YAML_Doc::YAML_Doc(const std::string& miniApp_Name, const std::string& miniApp_Version, const std::string& destination_Directory, const std::string& destination_FileName){
+  miniAppName = miniApp_Name;
+  miniAppVersion = miniApp_Version;
+  destinationDirectory = destination_Directory;
+  destinationFileName = destination_FileName;
+}
+
+//inherits the destructor from YAML_Element
+YAML_Doc::~YAML_Doc(void){
+}
+
+/*
+* generates YAML from the elements of the document and saves it
+* to a file
+*/
+string YAML_Doc::generateYAML(){
+  string yaml;
+  yaml =  yaml + "Mini-Application Name: " + miniAppName + "\n";
+  yaml =  yaml + "Mini-Application Version: " + miniAppVersion + "\n";
+  for(size_t i=0; i<children.size(); i++){
+    yaml = yaml + children[i]->printYAML("");
+  }
+
+  time_t rawtime;
+  tm * ptm;
+  time ( &rawtime );
+  ptm = localtime(&rawtime);
+  char sdate[25];
+  //use tm_mon+1 because tm_mon is 0 .. 11 instead of 1 .. 12
+  sprintf (sdate,"%04d:%02d:%02d-%02d:%02d:%02d",ptm->tm_year + 1900, ptm->tm_mon+1,
+    ptm->tm_mday, ptm->tm_hour, ptm->tm_min,ptm->tm_sec);
+
+  string filename;
+  if (destinationFileName=="") 
+    filename = miniAppName + "-" + miniAppVersion + "_";
+  else 
+    filename = destinationFileName;
+  filename = filename + string(sdate) + ".yaml";
+  if (destinationDirectory!="" && destinationDirectory!=".") {
+    string mkdir_cmd = "mkdir " + destinationDirectory;
+#ifdef REDSTORM
+    mkdir(destinationDirectory.c_str(),0755);
+#else
+    system(mkdir_cmd.c_str());
+#endif
+    filename = destinationDirectory + "/" + destinationFileName;
+  }
+  else 
+    filename = "./" + filename;
+
+  ofstream myfile;
+  myfile.open(filename.c_str());
+  myfile << yaml;
+  myfile.close();
+  return yaml;
+}
+
+

ref/common/YAML_Doc.hpp

@@ -0,0 +1,122 @@
+//@HEADER
+// ************************************************************************
+// 
+//               Mantevo: A collection of mini-applications for HPC
+//                 Copyright (2008) Sandia Corporation
+// 
+// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
+// license for use of this work by or on behalf of the U.S. Government.
+// 
+// This library is free software; you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation; either version 2.1 of the
+// License, or (at your option) any later version.
+//  
+// This library 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
+// Lesser General Public License for more details.
+//  
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+// USA
+// Questions? Contact Michael A. Heroux ([email protected]) 
+// 
+// ************************************************************************
+//@HEADER
+
+// Changelog
+//
+// Version 0.1
+// - Initial version.
+//
+/////////////////////////////////////////////////////////////////////////
+
+#ifndef YAML_DOC_H
+#define YAML_DOC_H
+#include <string>
+#include <vector>
+#include "YAML_Element.hpp"
+
+//! The Mantevo YAML_Doc class for the uniform collecting and reporting of performance data for mini-applications
+
+/*!
+
+The YAML_Doc class works in conjuction with the YAML_Element class to facilitate easy collecting and reporting of YAML-formatted
+data that can be then registered with the Mantevo results collection website.
+
+\code
+
+//EXAMPLE CODE FOR GENERATING YAML
+
+  YAML_Doc doc("hpccg","1.0");
+  doc.add("final_residual",1.4523e-13);
+  doc.add("time","4.893"); 
+ 
+//note: the following line will remove the data (4.890) associated with "time"
+  doc.get("time")->add("total",4.243);
+
+//note:  the following line will likewise remove the data (1.243) associated with "time"
+  doc.get("time")->get("total")->add("time",2.457);
+  doc.get("time")->get("total")->add("flops",4.88e5);
+  doc.get("time")->add("ddot",1.243);
+  doc.get("time")->add("sparsemv","");
+  doc.get("time")->get("sparsemv")->add("time",0.3445);
+  doc.get("time")->get("sparsemv")->add("overhead","");
+  doc.get("time")->get("sparsemv")->get("overhead")->add("time",0.0123);
+  doc.get("time")->get("sparsemv")->get("overhead")->add("percentage",0.034);
+  cout << doc.generateYAML() << endl; 
+  return 0;
+
+\endcode
+
+Below is the output generated by the above code:
+
+\verbatim
+
+final_residual: 1.4523e-13
+time: 
+  total:
+    time: 2.457
+    flops: 4.88e5
+  ddot: 1.243
+  sparsemv:
+    time: 0.3445
+    overhead:
+      time: 0.0123
+      percentage: 0.034
+
+\endverbatim
+
+\note {No value is allowed to be attached to a key that has children.  If children are added to a key, the value is simply set to "".}
+
+*/
+class YAML_Doc: public YAML_Element {
+  public:
+  //! Constructor: accepts mini-application name and version as strings, optionally accepts directory and file name for printing results.
+  /*!
+    The sole constructor for this class accepts and name and version number for the mini-application as well as optional directory 
+    and file name information for results that are generated by the generateYAML() method.
+    \param miniApp_Name (in) string containing name of the mini-application
+    \param miniApp_Version (in) string containing the version of the mini-application
+    \param destination_Directory (in, optional) path of diretory where results file will be stored, relative to current working directory. 
+           If this value is not supplied, the results file will be stored in the current working directory.  If the directory does not exist
+	   it will be created.
+    \param destination_FileName (in, optional) root name of the results file.  A suffix of ".yaml" will be automatically appended.  If no
+           file name is specified the filename will be constructed by concatenating the miniAppName + miniAppVersion + ".yaml" strings.
+  */
+  YAML_Doc(const std::string& miniApp_Name, const std::string& miniApp_Version, const std::string& destination_Directory = "", const std::string& destination_FileName = "");
+  //! Destructor
+  ~YAML_Doc();
+  //! Generate YAML results to standard out and to a file using specified directory and filename, using current directory and miniAppName + miniAppVersion + ".yaml" by default
+  std::string generateYAML();
+
+protected:
+  std::string miniAppName;
+  std::string miniAppVersion;
+  std::string destinationDirectory;
+  std::string destinationFileName;
+};
+#endif /* YAML_DOC_H */
+