Technical Report

NREL/ TP-6A1-44799

Revised July 2009

Hydrogen Macro System Model 

User Guide, Version 1.2.1

Mark Ruth and Victor Diakov

National Renewable Energy Laboratory

Tim Sa and Mike Goldsby

Sandia National Laboratories

Karen Genung, Ryan Hoseley, Ashley Smith, 

and Elvin Yuzugullu

SENTECH, Inc.
National Renewable Energy Laboratory

1617 Cole Boulevard, Golden, Colorado 80401-3393

303-275-3000 • www.nrel.gov

NREL is a national laboratory of the U.S. Department of Energy

Office of Energy Efficiency and Renewable Energy

Operated by the Alliance for Sustainable Energy, LLC

Contract No. DE-AC36-08-GO28308

Technical Report

NREL/ TP-6A1-44799

Revised July 2009

Hydrogen Macro System Model 

User Guide, Version 1.2.1

Mark Ruth and Victor Diakov

National Renewable Energy Laboratory

Tim Sa and Mike Goldsby

Sandia National Laboratories

Karen Genung, Ryan Hoseley, Ashley Smith, 

and Elvin Yuzugullu

SENTECH, Inc.

Prepared under Task No. HS07.1003
NOTICE

This report was prepared as an account of work sponsored by an agency of the United States government. 

Neither the United States government nor any agency thereof, nor any of their employees, makes any 

warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or 

usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not 

infringe privately owned rights. Reference herein to any specific commercial product, process, or service by 

trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, 

recommendation, or favoring by the United States government or any agency thereof. The views and 

opinions of authors expressed herein do not necessarily state or reflect those of the United States 

government or any agency thereof.

Available electronically at http://www.osti.gov/bridge

Available for a processing fee to U.S. Department of Energy

and its contractors, in paper, from:

U.S. Department of Energy

Office of Scientific and Technical Information

P.O. Box 62

Oak Ridge, TN 37831-0062

phone: 865.576.8401

fax: 865.576.5728

email: mailto:reports@adonis.osti.gov

Available for sale to the public, in paper, from:

U.S. Department of Commerce

National Technical Information Service

5285 Port Royal Road

Springfield, VA 22161

phone: 800.553.6847

fax: 703.605.6900

email: orders@ntis.fedworld.gov

online ordering: http://www.ntis.gov/ordering.htm

Printed on paper containing at least 50% wastepaper, including 20% postconsumer waste
iii 

Table of Contents 

List of Figures ............................................................................................................................................ iv

List of Tables .............................................................................................................................................. iv

List of Acronyms ........................................................................................................................................ iv

1 Overview ................................................................................................................................................ 1

1.1 Description ...........................................................................................................................1

1.2 Goals and Objectives ...........................................................................................................1

1.3 Scope ....................................................................................................................................2

1.3.1 Pathway/Well-to-Wheels (WTW) Analysis ...............................................................2

1.3.2 Additional Analysis Capability ...................................................................................3

1.4 Model Structure ...................................................................................................................3

1.5 Component Models ..............................................................................................................5

1.6 Restrictions, Assumptions, Constraints ...............................................................................7

1.7 Validation Methodology ......................................................................................................7

2 Interfacing with the Application and Guide to MSM User Types ..................................................... 9

2.1 Basic User ............................................................................................................................9

2.2 Comprehensive User ..........................................................................................................10

2.3 Model Developer ...............................................................................................................10

2.4 Software Architect .............................................................................................................10

2.5 System Administrator ........................................................................................................11

3 Operating the MSM as a Basic User ................................................................................................. 12

3.1 Getting Started ...................................................................................................................12

3.2 Parameter Inputs ................................................................................................................14

3.3 Viewing Results .................................................................................................................25

4 Operating the MSM as a Comprehensive User ................................................................................ 27

4.1 Getting Started ...................................................................................................................27

4.2 MSM Files .........................................................................................................................28

4.3 User Inputs .........................................................................................................................28

4.3.1 Editing the .xml File ..................................................................................................29

4.3.2 Editing the Component Models of the MSM ............................................................33

4.3.3 Editing the Batch File ...............................................................................................35

4.4 Running the MSM and Obtaining Outputs ........................................................................36

4.5 Running the multi parameter option with MSM ................................................................38

4.6 Using the Autotest Feature.................................................................................................40

5 Conclusion .......................................................................................................................................... 42
iv

List of Figures

Figure 1. The GUI and the MSM operation process....................................................................... 4

Figure 2. Fuel and vehicle cycles examined in the GREET model ................................................ 6

Figure 3. Hierarchy and types of data extracted from the component models to feed into the 

MSM ............................................................................................................................................... 7

Figure 4. Java Web Start............................................................................................................... 12

Figure 5. Locally signed Java application archive file ................................................................. 13

Figure 6. Log-in dialogue box ...................................................................................................... 13

Figure 7. The MSM GUI .............................................................................................................. 14

Figure 8. View Submissions window ........................................................................................... 16

Figure 9. View Detailed Info window .......................................................................................... 16

Figure 10. Models pane................................................................................................................. 17

Figure 11. Display of simulations................................................................................................. 24

Figure 12. Display of results......................................................................................................... 25

Figure 13. Ruby download site ..................................................................................................... 27

Figure 14. .xml file sections.......................................................................................................... 30

Figure 15. Original units for liquidTruckTotalTime..................................................................... 31

Figure 16. New units for liquidTruckTotalTime .......................................................................... 31

Figure 17. Display of “Allowable Values” for data items............................................................ 33

Figure 18. Window to confirm MS Excel 2003 settings .............................................................. 34

Figure 19. Steps to adjust macro security ..................................................................................... 35

Figure 20. Window used to change filenames of edited files....................................................... 36

Figure 21. MSM running in a command prompt .......................................................................... 37

Figure 22. Sample log.txt file........................................................................................................ 38

Figure 23. Sample parameter schedule file................................................................................... 39

Figure 24. Options menu............................................................................................................... 40

Figure 25. Example of directory structure for running autotest.................................................... 40

List of Tables

Table 1: Unit names...................................................................................................................... 31

Table 2. Sample entries from the output.csv file .......................................................................... 38

List of Acronyms

API Application programming interface

CG Conventional Gasoline

DBMS Database management system

DOE Department of Energy

EIA Energy Information Administration

FCV Fuel Cell Vehicle

FTE Full Time Employee

GDS Global data set
v

GGE Gasoline gallon equivalent

GHG Greenhouse gas

GREET Greenhouse Gases, Regulated Emissions, and Energy Use in Transportation

GUI Graphical user interface

GV Gasoline Vehicle

H2 Hydrogen

HDSAM H2A Delivery Scenario Analysis Model

HTTP Hypertext protocol

HyARC Hydrogen Analysis Resource Center

ICE Internal Combustion Engine

JRE Java Runtime Environment

MS Microsoft

MSM Macro System Model

NG Natural Gas

NREL National Renewable Energy Laboratory

PHP Hypertext preprocessor

R&D Research and development

RFG Reformulated Gas

SIO Systems Integration Office

SMR Steam Methane Reforming

SNL Sandia National Laboratories

SOAP Simple Object Access Protocol (Simple XML-based protocol)

WTW Well-to-Wheels

VOC Volatile organic compound
1

1 Overview

1.1 Description

The Hydrogen Macro System Model (MSM) is a simulation tool that links existing and emerging 

hydrogen-related models to perform rapid, cross-cutting analysis. The MSM’s current 

instantiation links the H2A Production, H2A Delivery Scenario Analysis Model (HDSAM), and 

GREET models, thus allowing analysis of the economics, primary energy-source requirements, 

and emissions of hydrogen production and delivery pathways. Additional work planned in the 

future includes additional hydrogen production and delivery technologies and linking HyPro and 

other models to the MSM. At this time, the MSM is the first model to simulate cost, energy use, 

and emissions of the entire hydrogen system (including feedstock, conversion, infrastructure, and 

vehicles) with the level of technical detail required to meet a range of needs in an integrated 

fashion, and its analyses and sensitivity runs can provide a basis for decisions regarding focus of 

research needs.

Furthermore, the MSM tool can help users understand the effects of varying parameters on a 

pathway’s results without requiring expertise in all of its models. The MSM facilitates

consistency between the methodologies and assumptions of each model by transferring 

information between models. Because the models are linked and data are consistent, the current 

instantiation of the MSM can assist analysts in understanding the effects of changing scenarios 

(i.e., hydrogen production / delivery options) and parameters (e.g., efficiencies and unit costs) on 

the pathway costs, WTW energy requirements, and WTW emissions. Future instantiations are 

expected to allow analysts to estimate the effects on hydrogen buildout scenarios, their potential 

economics, energy requirements, and emissions.

The MSM was jointly developed by the Systems Integration office (SIO) at the National 

Renewable Energy Laboratory (NREL) and the Sandia National Laboratories (SNL). The SIO 

provides domain expertise and leads the project; SNL provides computer expertise.

1.2 Goals and Objectives

The MSM was designed to act as an overarching system that provides a cross-cutting analysis 

and simulation capability to the U.S. Department of Energy’s (DOE) Hydrogen Program. In 

addition, MSM may be used to guide the development of other similar simulation tools.

MSM was developed to accomplish the following specific objectives:

• To perform rapid, cross-cutting analysis through a single model by linking existing 

applicable models

• To improve consistency of technology representation (i.e., consistency between models)

• To allow for consistent use of hydrogen models without requiring all users to be experts 

in all models

• To support decisions regarding programmatic investments, focus of funding, and research 

milestones through analyses and sensitivity runs
2

1.3 Scope

The MSM can currently perform pathway, also known as well-to-wheels (WTW), analysis of 

hydrogen production and delivery pathways. In the future, spatial and temporal models will be 

added to the MSM to allow users to answer more complex questions regarding the market 

dynamics and infrastructure needs related to developing a hydrogen economy. 

1.3.1 Pathway/Well-to-Wheels (WTW) Analysis

Pathway, or WTW, analysis responds to the need to understand costs, the breakdown of these 

costs, energy use, and emissions related to different hydrogen production/delivery pathways. 

This approach looks at these pathways from the extraction of feedstock for hydrogen, through 

the production, storage, and delivery processes, and all the way to the use of hydrogen in 

vehicles. Through its links to component models such as the H2A Production model, the 

Hydrogen Delivery Scenario Analysis Model (HDSAM),

1

With the MSM’s ability to integrate multiple variables, the user may modify these variables to 

observe valuable results highlighting different aspects of various technologies and pathways. The 

primary variables currently included in the WTW analysis structure of the MSM are technology 

year, city size and hydrogen fuel penetration, production and delivery technology, and vehicle 

fuel economy. In some cases, users may also choose whether to use a model’s default input 

values or their own.

and the Greenhouse Gases, Regulated 

Emissions, and Energy Use in Transportation (GREET) model, the MSM is capable of 

performing a comprehensive WTW analysis that provides users with details such as the amount 

and type of feedstock used to produce hydrogen, efficiencies of different technologies, energy

use and emissions of various pathways, hydrogen production capacity to meet demand, and cost 

of hydrogen at the pump achievable under different scenarios.

The ability to compare critical factors such as levelized hydrogen costs at the pump using 

different hydrogen production/delivery technologies, raw material needs required to meet a city’s 

potential hydrogen demands, energy use, efficiencies and emissions profile (CO2, CH4, N20, 

GHG, VOC, CO, NOx, PM10, SOx) of hydrogen use for varying populations and hydrogen 

penetration levels is a capability that delivers a comprehensive and cross-cutting view of factors 

related to the development of a hydrogen economy.

As of February 2009, the following production and delivery technologies have been included in 

the MSM and made available in its GUI:

• Central production technologies2

o Biomass gasification

o Coal gasification with carbon dioxide sequestration 

o Coal gasification without carbon dioxide sequestration

o Natural gas reforming with carbon dioxide sequestration

 1 H2A analyses include the H2A Production model (and case studies) and H2A delivery analysis (HDSAM and 

Delivery Components Model). 

2 Production is distributed when hydrogen is produced at refueling stations; central production requires hydrogen 

delivery from the plant to refueling stations.
3

o Natural gas reforming without carbon dioxide sequestration

o Electrolysis using electricity generated with wind turbines

o High temperature electrolysis with nuclear reactors (available in 2015+)

• Distributed production technologies

o Electrolysis

o Natural gas reforming

o Ethanol reforming

• Delivery technologies

o Piping of gaseous hydrogen

o Truck-transport of liquid hydrogen

1.3.2 Additional Analysis Capability

As additional component models are integrated into the MSM (such as spatial and temporal 

models), the structure and components of the MSM will allow users to discover answers to more 

complex questions regarding the market dynamics and infrastructure needs related to 

transitioning to a hydrogen economy.

1.4 Model Structure

Figure 1 illustrates how the MSM software application interconnects the component models by 

the following means:

• Unifying Framework: Implemented in the Ruby scripting language; consists of model 

application programming interfaces (APIs), model control scripts, unit conversion 

facility, global data set (GDS), and execution control

• Graphical User Interface (GUI): Implemented in Java and delivered via Java Web Start 

and the user’s installed browser

• Database Management System (DBMS): Implemented in MySQL and contains archived 

jobs and user data

• Web Services: Because all the component models are currently housed on a single 

machine, Web services are not being used. In the near future, component models are 

expected to be housed in different locations and Apache Web services will be used to 

allow communication via HTTP.
4

Figure 1. The GUI and the MSM operation process

The general framework is extensible (accommodates new models with minimal difficulty), 

distributable (can be used by multiple people in different areas of the country), and scalable to 

large numbers of participating models.

Through the GUI, the user inputs variables such as timeframe, production technology, feedstock, 

delivery method, city size, and penetration of the technology.3

The current MSM version co-locates all back-end resources on a single server (application 

server) while the future planned version will allow models, their APIs, and their control scripts to 

be located at the model owner’s/developer’s site or other location (model server). Because the 

models are currently co-located with the unifying framework, SOAP (a simple XML-based 

protocol that lets applications exchange information over HTTP) is not necessary. This protocol

will more likely be used in future versions of the MSM when some models are physically located 

in other places.

User input data is initially 

transferred to the GDS, which holds all data in a consistent set of units. As each component 

model is run, data from it is transferred to the GDS, and calculations are done by the GDS script. 

Input data for subsequent models are taken from the GDS. As the capabilities of the MSM are 

expanded in the future, optimization routines and solution methodology schemes may also be 

added.

 3 Future capabilities of the MSM will involve significantly more parameter inputs available for the user through the 

Web interface. 
5

1.5 Component Models

The MSM is built on a type of federated object model framework similar to that used in High 

Level Architecture. To date, it integrates the following models:

• Hydrogen Analysis Resource Center (HyARC).

4

• HDSAM.

HyARC provides well-documented, 

reliable physical property information that can serve as a basis for accurate analysis of 

hydrogen production/delivery costs, markets, policy options, and other key analysis 

topics. The Resource Center features the Hydrogen Data Book (with a wide range of 

hydrogen and fuel cell information valuable to infrastructure analysis), links to external 

data from the Energy Information Administration (EIA) and other government entities 

specializing in hydrogen and fuel cell analysis, DOE Hydrogen Program analysis 

guidelines and assumptions, and hydrogen calculation tools. Values from HyARC, 

including heating values and densities, are transferred to other models in MSM to ensure 

consistency.

5

• H2A Production

HDSAM is a delivery-scenario model that links various hydrogen delivery 

component costs to develop capacity/flow parameters for a hydrogen delivery 

infrastructure. This approach allows the model to calculate the full cost of hydrogen 

delivery and accounts for any tradeoffs between components. The structure provided by 

this model allows the efficient examination of new technologies, alternative delivery 

pathways/packaging solutions, and the effect of demand density and scale. HDSAM uses 

financial calculation methodologies and parameters consistent with H2A Production to 

provide a “snap shot” of delivery cost results based upon input assumptions.

6 and Case Studies.7

• GREET.

The H2A Production model is used to assess the 

cost of producing hydrogen for central and forecourt (filling station) technologies. Users 

are permitted to define characteristics of the production such as process design, capacity, 

capacity factor, efficiency, feedstock requirements, capital costs, and operating costs. For 

more customized analyses, users may also manipulate various financial parameters 

including internal rate of return, plant life, feedstock costs, and tax rate. Case studies 

were built on the H2A Production model where the process characteristics and 

parameters are defined for some hydrogen production processes. In the MSM, 

assumptions and data on several key technologies were taken from those H2A Production 

case studies.

8

 4

Created by the Argonne National Laboratory, the GREET model allows for 

the evaluation of various vehicle and fuel combinations on a full fuel-cycle/vehicle-cycle 

basis (Figure 2). The MSM uses the GREET 1 Series model (version 1.8b), which

includes only the fuel-cycle portion, allowing researchers to evaluate a fuel cycle from 

the well to wheels. The MSM does not use the GREET 2 Series models, which include 

the vehicle-cycle. More than 100 fuel production pathways (e.g., corn to ethanol and

soybean-based biodiesel) are included in GREET 1.8b to calculate the consumption of 

total energy, greenhouse gas emissions (primarily carbon dioxide, methane, and nitrous 

http://hydrogen.pnl.gov/cocoon/morf/hydrogen

5 http://www.hydrogen.energy.gov/h2a_delivery.html

6 http://www.hydrogen.energy.gov/h2a_production.html

7 http://www.hydrogen.energy.gov/h2a_prod_studies.html

8 http://www.transportation.anl.gov/software/GREET/index.html
6

oxide), and six criteria pollutants. For use in the MSM, energy requirements in H2A 

Production and HDSAM are converted to standard GREET inputs (yields, shares, 

distances, etc.).

Figure 2. Fuel and vehicle cycles examined in the GREET model

MSM links these four individual component models by integrating the various elements of each

one that are relevant to hydrogen production, distribution, storage, vehicle technologies and 

widespread deployment of a hydrogen fueling infrastructure. Figure 3 demonstrates the hierarchy 

of data, beginning with physical properties from HyARC feeding into delivery data from 

HDSAM, followed by production data from H2A Production, and finally accessing vehicle and 

WTW data from GREET (delivery data is generated before production to set the city parameters 

and will be used to scale production facilities in the future). Data from the most applicable model 

is used in cases where models may contradict. In such a case, data are taken from the component 

model that is believed to include the most detail and accuracy. For example, for hydrogen 

production yield values, H2A Production data are preferred over data from GREET, or HDSAM 

data are preferred over GREET data for liquefaction-efficiency values. In some cases, users are 

able to decide which values to use, such as in the case of vehicle fuel economy, with which the 

users may opt to use values from HDSAM or GREET9

 9 The option to select GREET as the source of data for vehicle fuel economy is currently not available.

or enter their own.
7

Figure 3. Hierarchy and types of data extracted from the 

component models to feed into the MSM

1.6 Restrictions, Assumptions, Constraints

Because individual component models pre-date the MSM in many cases, they have functionality 

apart from their use in the MSM. Modification of these models to facilitate their incorporation 

into the MSM is undesirable and should not be necessary. The MSM is being designed so that it 

will be able to accommodate the interaction of models that may be run only remotely from their 

original institutions. Default assumptions in the MSM are based on assumptions included in the 

component models. 

1.7 Validation Methodology

The MSM developers first consulted with each of the component models’ developers to ensure a 

full understanding of each model’s purpose, its intended use, and its inputs and outputs, which 

were incorporated into the MSM before utilizing the model within the MSM. Exhaustive lists of 

inputs and results were compiled based on these discussions. As the component models were 

linked to the MSM, investigators defined terms and created calculation methodologies. Gaps and 

additional research needs were identified through this validation process and were fed back to the 

developers of each individual component model.

Once the component models were linked by the MSM, many comparisons to other analyses were 

also performed. This involved a meticulous review of inputs and results as well as mapping 

between results from different analyses, including various production and delivery methods. If 

differences between the analyses were caused by inputs or outputs omitted by the MSM, they 
8

were added to the MSM. Usually, the MSM was found to include additional inputs that had been 

omitted in analyses undertaken before the MSM was developed.

As more members of the hydrogen community use the MSM, interaction will take place to

discuss findings and methodologies in more detail and to reach consensus on the MSM approach 

and defined parameters. Many of the expected users are also developers of component models,

and this process is expected to also provide feedback to their modeling efforts. This process will 

create a continuous information feedback loop between MSM users and developers of both the 

MSM and component models.
9

2 Interfacing with the Application and Guide to MSM User Types

The structure and capabilities of the MSM allow it to address the diverse needs of its users. Some 

users may desire only a “snap shot” of different technologies and pathways while others may 

wish to investigate options in more detail, searching for answers to specific techno-economic and 

environmental concerns. This section describes the differing perspectives of end users and the 

range of approaches to utilizing the MSM. There is some overlap among these perspectives and 

processes. The end user types may be categorized as:

• Basic User

• Comprehensive User

Other roles within the MSM include:

• Model Developer

• Software Architect

• System Administrator

2.1 Basic User

The primary value of the MSM is its ability to link existing models across multiple platforms, 

allowing for consistent cross-cutting analysis. The basic users of the MSM, such as researchers, 

policy makers, and analysts, will find the tool useful for quickly analyzing a variety of scenarios 

using industry-accepted assumptions. Section 3 of this manual provides further detail to assist 

users in navigating the graphical user interface (GUI) of the model.

The MSM has been designed to allow users to analyze the financial, environmental, transitional,

and R&D issues associated with the transition to a hydrogen economy. Basic end users can use 

the MSM to answer cross-cutting questions that were previously difficult to answer in a 

consistent and timely manner due to variations in assumptions and methodologies among 

different models. Examples include the following: 

• How much fossil fuel versus renewable energy use does a given hydrogen pathway 

require?

• What is the overall efficiency of the pathway considered versus the efficiency of its 

components?

• How much hydrogen needs to be produced to supply a given city’s demands?

• What are the raw materials needed to meet those demands?

• What is the resulting emissions profile if hydrogen is produced to meet a given city’s 

demands?

• What is the comparison of hydrogen costs at the pump using different hydrogen 

production technologies?
10

As the MSM develops and additional component models are integrated into it, other complex 

questions may be answered that will provide insight into both spatial and temporal issues:

• How might different locations affect the economics, energy requirements, and emissions 

of hydrogen pathways?

• Does a specific technology make more sense in one location than another?

• How does one identify stumbling blocks that could affect transition paths? Could R&D 

overcome them?

• What impacts could competing technologies have on transition?

• How do potential transition pathways compare?

• What effects could policy and incentives have on transition?

2.2 Comprehensive User

After exploring the basic user capabilities of the MSM, comprehensive users may find that they 

need additional functionality. These users can manually edit the input.xml file for direct 

submission to the application server. Although this option affords more flexibility, it is important 

to note that only minimum error checking takes place on the input file; results obtained by the 

comprehensive user are therefore more likely to be in error than those obtained by basic users. It 

is therefore necessary that comprehensive users have an advanced understanding of the input 

parameters they are examining. 

In addition to editing the input.xml file, comprehensive users can also modify MSM inputs by

using the command line or by selecting personalized component models. All of these options can 

be used to perform more detailed analyses and to explore different outputs, and they are further 

explained in Section 4.

2.3 Model Developer

Model developers for models such as H2A Production or GREET update the MSM scripts and 

APIs of their own models as the MSM is updated. The MSM scripts and APIs perform the data 

transfer between the component model and the MSM structure so the model developer needs to 

identify parameters to transfer between models and explore how their models interact with the 

MSM framework and add those parameters to the model scripts and APIs. Model developers do 

not necessarily need to modify the scripts and APIs but will initially work with the MSM 

principal investigator to perform these tasks.

2.4 Software Architect

The software architect develops the MSM, including the GUI. As the primary application 

developer, they understand the file structure and working with the various languages used in the 

MSM such as Ruby, PHP, MySQL and Java. Currently, experts at Sandia National Laboratories

are the exclusive software architects for the MSM and are responsible for the system design and 

evolution. Domain expertise is provided by the principal investigator and codified by the 

software architects.
11

2.5 System Administrator

System administrators maintain computers where the component models, the executable MSM 

code, Web server, DBMS, and/or user interface are located. Additionally, they install application 

updates, perform periodic back-ups of data, and grant user access as authorized by the principal 

investigator. For example, component models are expected to be housed on servers at host 

organizations. When the MSM is linked to those models, staff at those organizations will need to 

become MSM system administrators to enable data transfers between their models and the MSM.
12

3 Operating the MSM as a Basic User

The GUI of the MSM allows for a convenient and easy-to-use tool to aid those investigating

different technology pathways in the transition to a hydrogen economy. The sections below 

describe steps to follow in navigating this interface, inputting parameters, and obtaining results.

3.1 Getting Started

Basic users using the MSM online interface for the first time must request an account from the 

MSM principal investigator, Mark Ruth of NREL, at Mark_Ruth@nrel.gov. A user name and 

password is then e-mailed to the user for use at http://h2-msm.ca.sandia.gov/.

As shown in Figure 4, the user is presented with a Java Web Start launch option to run the online 

version of the model.

Figure 4. Java Web Start 

When launched, the installed version of the Java Runtime Environment (JRE)10

If either Netscape Navigator or Mozilla Firefox is the user’s preferred browser, once Java Web 

Start is selected, a dialogue box will be displayed. The option “Open with Java Web Start 

Launcher” should be selected.

on the user’s 

computer is automatically checked, and a locally signed Java Application Archive file is

presented to the user to accept for downloading. As this is a locally signed file, a warning 

message indicating that “the application’s digital signature cannot be verified” will be displayed 

(Figure 5). The user may select “Always trust content from this publisher” to avoid seeing this 

prompt again in the future.

 10 The application is compiled under Java Development Kit (JDK) 6 and thus requires JRE version 6. As the 

application will not start if there is a mismatch with the JRE version on the user’s computer (or if Java is not 

installed at all), users should first check that Java is installed on their computer and install version 6 if they have an 

older version on their computer. If users are unsure, the “Do I have Java” link provided on the Java Web site 

(http://www.java.com) will check to see if Java is installed and, if so, will indicate the version installed, providing 

the user with an option to install the latest updates. 
13

Figure 5. Locally signed Java application archive file

A log-in dialogue box is then displayed (Figure 6), and the user provides the user ID and 

password. The “Mode” select box allows the user to choose which interface to operate under in 

inputting data and analyzing. The “interactive mode” should be selected because it is the only 

active mode at this time. After this, the user is able to view the GUI of the model (Figure 7) and 

start performing simulations.

Figure 6. Log-in dialogue box
14

Figure 7. The MSM GUI

Four tabs appear at the top of the GUI:

• Interactive: Use this tab to specify inputs or to select values to perform well-to-wheels 

analyses of different cases. The “Interactive” tab is currently the only active tab; more

details are provided below.

• Upload file: In the future, this tab will allow users to upload their own set of data to run 

simulations.

• Multi-param: In the future, this tab will allow for the analysis of additional parameters 

beyond WTW.

• Archive: In the future, this tab will access a database interface where the user can search 

his or her previous runs on specific criteria.

3.2 Parameter Inputs

The “Interactive” tab allows users to define the following parameters:

Four Tabs at the Top of the GUI

“Interactive” Tab inputs
15

• System: Currently, only pathway analyses can be run with the MSM. In the future, 

additional options may be made available. The input options below are for 

pathway/WTW analyses and may change for other analyses. 

• Year: The starting year of the simulated production/delivery scenario

• Production Size/Delivery: The scale/location of hydrogen production (i.e., central or 

distributed production) and the delivery mode for cases with central production (i.e., 

gaseous hydrogen via pipelines or liquid hydrogen via trucks).

• Feedstock/Process: Feedstock options that depend on the selected production size 

o For “central production”: Coal gasification (with or without carbon 

sequestration), steam methane reforming (SMR) of natural gas (with or without 

carbon sequestration), nuclear high temperature electrolysis (for years 2015+)

wind electrolysis,11

o For “distributed production”: Electrolysis (using grid electricity), ethanol 

reforming, and on-site SMR of natural gas. 

and biomass (woody) gasification. 

• City Characteristics: The population and hydrogen market penetration values to be 

considered (The default range of “50,000 and 20,000,000 inclusive” is given for 

population, and a minimum of “5%” is given for the hydrogen’s market penetration 

percentage.)

• Vehicle Fuel Economy: MSM values from the HDSAM or GREET12

The user may also enter a title and short description for each case using the “Title” and 

“Description” boxes

models or specified 

user input values [entered in mi/GGE (gasoline gallon equivalent)]. 

13

 11 This option is currently not available. 

provided in the lower part of the window. Later, when viewing a 

submission, the title can be seen and, using the “Get Info” button (see figures 8 and 9), the 

description may be viewed as well. This will allow the user to identify and remember easily the 

details of a specific case they had run before.

12 Ibid. 13 At this time, the information entered into the “Description” box is stored but not visible on the GUI. In the future, 

it will be part of the run database and will be visible. 
16

Figure 8. View Submissions window

Figure 9. View Detailed Info window

The right side of the window includes a “Models” pane where the component models that 

underlie the framework of the MSM are presented. The version of the models being used is noted 

by the model name next to each input value (This information is also provided in the results 

window—see section 3.3). 

Should the user wish to define additional parameters, the “Edit Detailed Inputs” button located at 

the bottom left of the screen may be utilized. Here, several categories can be found and, once 

selected, manipulated using the pull down menu labeled “Value” at the bottom right of the 

screen. By changing the selection of the “Value” pull down menu from a model name to “user 

input” any value may be entered to suit any situation. A general description of the various 

detailed inputs available for manipulation will be given. Care must be taken when using these 

Use this button to view the 

description of the simulation.
17

inputs since, once the detailed inputs section has been entered, the regular input values may not 

be changed without losing any alterations made to the detailed inputs.

Figure 10. Models pane

• Feedstock, Utilities

o Electricity generation mix: The combination of various types of power generating 

methods (coal, nuclear, renewable, etc...) used to create energy for a given 

region.

 CA mix: California

 NE U.S. mix: Northeast United States

 U.S. mix: United States

 Wind only: Power generated exclusively by wind

Model Being Used as the Source

The pull down menu used to change 

the source of a variable from a model 

to the user.
18

o Utilities, co-products:

 Source of electricity co-product production: The amount of electricity in 

kilowatt hours produced per kilogram of hydrogen.

 Source of electricity co-product cost: The cost in dollars to produce one 

kilowatt hour of electricity.

 Source of natural gas consumption: The rate at which natural gas is 

consumed per mass of hydrogen created.

 Source of natural gas utility price: The cost of a cubic meter of natural gas.

 Source of utility electric consumption: The amount of electricity required 

to generate a kilogram of hydrogen.

 Source of utility electric price: The cost of one kilowatt hour of electricity.

o Coal

 Source of bituminous coal feedstock consumption: The ratio of the mass 

of coal feedstock consumed per unit mass of hydrogen produced. 

 Coal feedstock price: The price of coal in dollars per kilogram.

o Energy use for carbon capture in H2 central plants: The energy in joules per 

kilogram of carbon required to sequester carbon particles from exhaust in order to 

reduce pollution. 

o Natural Gas

 Source of natural gas feedstock consumption: The volume of natural gas 

required to generate one kilogram of hydrogen.

 Natural gas feedstock price: The cost of a cubic meter of natural gas.

o Electricity feedstock use and cost characterization

 Source of electricity feedstock consumption: The electricity in kilowatt 

hours required to generate one kilogram of hydrogen.

 Source of electricity feedstock cost – industrial electricity only: The cost 

of one kilowatt hour of electricity

o Nuclear

 Source of heat feedstock consumption: The heat in megawatt hours 

required to generate one kilogram of hydrogen.
19

 Feedstock heat price source: The cost of one megawatt of heat.

o Biomass

 Source of biomass feedstock consumption: The mass ratio of how much 

biomass must be consumed in order to produce one kilogram of hydrogen.

 Source of biomass feedstock cost: The price of a kilogram of biomass.

 Source of poplar farming energy use: The energy in mega joules required 

to grow one kilogram of poplar tree.

• Production Facility:

o Source of production total capital investment: Total monetary investment in the 

production of hydrogen.

o Source of production capacity factor: The ratio of the projected actual output of a 

plant over time against its maximum possible output during that time.

o Source of number of production FTEs: The number of full-time employee 

equivalents.

• Source of internal rate of return: The average projected annual compound rate of return 

received by an investor over the life of their investment. This is a key indicator used by 

institutions in appraising their investments. 

• Delivery

o Pipeline delivery

 Pipeline losses

• Source of H2 loss in pipeline: The percentage of hydrogen lost in 

the pipeline delivery system.

• Source of H2 loss during compression: The percentage of 

hydrogen lost when it is being compressed.

 Pipeline length from plant to city: Pipeline length for fuel delivery from 

plant to city.

o Liquid H2 delivery

 Liquefier
20

• Source of liquefier efficiency: The hydrogen liquefied divided by 

the sum of the hydrogen liquefied plus the energy required for the 

liquefaction.

• Electricity generation mix for liquefaction in NG plant:

• Electricity generation mix for liquefaction in solar plant:

• Electricity generation mix for liquefaction in nuclear plant:

• Electricity generation mix for liquefaction in coal plant:

• Electricity generation mix for liquefaction in biomass plant:

o These represent the mix of electricity producing methods 

responsible for providing the plant with any additional 

electricity that it may require.

 Storage

• Days of storage at production plant/liquefier: The duration of the 

hydrogen’s stay at the plant after being generated.

• Recovery rate of boil-off gas in production plant: The amount of 

hydrogen recovered when it escapes as a gas.

• Recovery rate of boil-off gas in terminal: The percentage of 

hydrogen recovered when it escapes as a gas.

 Transport

• Liquid H2 boil-off rate in transportation from production

plant/liquefier to terminal: The percentage of hydrogen that boils 

off in one day while in the truck tank.

• Source of liquid H2 truck diesel fuel requirement: The fuel 

efficiency of liquid hydrogen transportation trucks running on 

diesel.

• Source of truck-tank loading losses: The amount of hydrogen lost 

as a truck tank is loaded.

• Source of truck-tank boil-off rate losses: The amount of hydrogen 

that boils off during transportation.

• Time in truck trailer for transport: The average number of days that 

the hydrogen will spend in a truck trailer while being transported.
21

• Recovery rate of boil-off gas during distributions: The percentage 

of boil-off gas that is recovered during the distribution process.

• Dispensing forecourt

o Forecourt capacity: The amount of hydrogen that can be contained within a 

distribution center.

o Gaseous H2 dispensing

 Source of energy efficiency when H2 piped from central plants with 

electric compressors: Efficiency of the compressor defined as the lower 

heating value of compressed hydrogen divided by the sum of the lower 

heating value of hydrogen entering the compressor plus the amount of 

electricity required for the compression.

 Source of hydrogen lost at gaseous forecourt station: Hydrogen lost 

(percent from total) at gaseous forecourt.

o Liquid H2 dispensing

 Time in liquid H2 forecourt stations: The average time hydrogen will 

spend at a forecourt station from the time it is delivered until it is 

dispensed.

 Recovery rate of boil-off in forecourt station: The percentage of hydrogen 

that is recovered after escaping into the gas phase.

 Source of liquid forecourt boil-off rate: The percent of the hydrogen stored 

at a forecourt that boils off every day.

o Time in forecourt storage: The amount of time that hydrogen will spend in 

forecourt storage from when it is delivered until it is dispensed.

• Vehicle characterization

o Baseline fuel efficiencies

 Source of gasoline internal combustion engine vehicles’ fuel efficiency: 

The value of the assumed average fuel economy achieved by vehicles with 

gasoline internal combustion engines in miles per gallon of gasoline

 Source of gasoline hybrid electric vehicles’ fuel efficiency: The value of 

the assumed average fuel economy achieved by vehicles with gasoline 

hybrid electric engines in miles per gallon of gasoline.

 Source of E-85 ethanol internal combustion engine vehicles’ fuel 

efficiency: The value of the assumed average fuel economy achieved by 
22

vehicles with E-85 ethanol internal combustion engines in miles per gallon 

of gasoline equivalent. 

o Gasoline and vehicle type

 Vehicle type: This entry has no effect on the model and is used merely to 

remind the user what is being modeled.

 Share of RFG in total gasoline use: The percentage of gasoline that has 

been reformulated and is no longer the conventional mixture.

 Type of oxygenate in RFG: Type of oxygenate used in the reformulated 

gasoline.

 Energy in 1 GGE: The amount of energy in BTUs that is contained within 

one gallon of gasoline or its equivalent in another substance.

o Source of vehicles per person: The assumed average number of vehicles owned 

by each person in the population.

• Default Values (Constants)

This section displays values being used within the calculations that cannot be altered by 

the user.

o Pipeline energy consumption

 Share of power generation done by turbine for pipeline compressions 

stations: Percentage of total power generated by a turbine.

 Share of power generation done by current NG engine for pipeline 

compressions stations: Percentage of total power generated by a natural 

gas engine.

 Share of power generation done by future NG engine for pipeline 

compressions stations: Percentage of total power generated by an 

advanced natural gas engine.

 Share of diesel fuel for piping: The percentage of energy provided by 

diesel fuel for piping.

 Share of NG fuel for piping: The percentage of energy provided by natural 

gas for piping.

 Share of residual oil fuel for piping: The percentage of energy provided by 

residual oil for piping.
23

 Share of H2 fuel for piping: The percentage of energy provided by 

hydrogen for piping.

 Share of electricity fuel for piping: The percentage of energy provided by 

diesel fuel for piping

o Gaseous H2 Dispensing

 Natural gas share of process fuels for gaseous H2 compression at central 

plants: The percentage of energy provided by natural gas for the 

compression of hydrogen.

 Electricity share of process fuels for gaseous H2 compression at central 

plants: The percentage of energy provided by natural bas for the 

compression of hydrogen.

o H2 FCV to gasoline ICE vehicle emissions ratio

 These categories represent the ratio of the assumed average emissions of a 

fuel cell vehicle running on volatile organic compounds compared 

vehicles employing internal combustion engines running on conventional 

gasoline and reformulated gasoline mixtures. Typically, these values will 

be zero since hydrogen fuel cells emit nothing but water.

• Ratio of FCV VOCs (emissions) to GVs fueled with CG and RFG: 

• Ratio of FCV VOCs (evaporative) to GVs fueled with CG and 

RFG: 

• Ratio of FCV CO emissions to GVs fueled with CG and RFG: 

• Ratio of NOx emissions to GVs fueled with CG and RFG: 

• Ratio of FCV CH4 emissions to GVs fueled with CG and RFG: 

• Ratio of FCV N2O emissions to GVs fueled with CG and RFG:

• Ratio of FCV exhaust PM10 emissions to GVs fueled with CG and 

RFG: 

• Ratio of FCV exhaust PM2.5 emissions to GVs fueled with CG 

and RFG:

 These categories represent the ratio of the assumed average release of 

particles of 10 micrometers or less (PM10) or 2.5 micrometers or less 

(PM2.5) by the brakes and tires of fuel cell vehicles compared to internal 

combustion vehicles running on conventional gasoline and reformulated 
24

gasoline compounds. The common values are almost always 1 since the 

braking systems and tires of both types of vehicles will be the same.

• Ratio of FCV brake and tire wear PM10 emissions to GVs fueled 

with CG and RFG:

• Ratio of FCV brake and tire wear PM2.5 emissions to GVs fueled 

with CG and RFG:

Each case runs once all the required information is submitted using the “Submit” button near the 

bottom of the window. Results are accessed by choosing the “View submissions” button at the 

bottom of the screen. This selection will display a “Simulations” window (Figure 11) listing all 

the cases that the user has run with the case number, title, and status.

Figure 11. Display of simulations

The status is displayed as “new” while the case is being processed. The user receives an e-mail 

once the simulation of his or her case is complete, and the “Simulation” window displays the 

case’s status as “complete.” If an error has been encountered, the e-mail message and simulation 

status indicate the error with an explanation.
25

3.3 Viewing Results

In the “Simulations” window, any of the cases listed may be viewed by highlighting that option 

and selecting the “View” button on the lower part of the window. This will open up a new 

window displaying summary results as shown in Figure 12.

14

Figure 12. Display of results

The top part of the window will display the components and energy flow of the case examined in 

graphical form. Right below the diagram, the following information will be displayed:

• Levelized Cost of Hydrogen at the Pump ($/kg)

• Energy Use and Emissions

o WTW Total Energy Use (Btu/mile)

o WTW Petroleum Energy Use (Btu/mile)

o WTW Fossil Energy Use (Btu/mile)

o WTW GHG Emissions (g/mile)

o WTP GHG Emissions (lb. CO2-equivalent/gge fuel available)

• Energy Efficiency

 14 Please note that the resolution of the results window has been set to 1000x800. As using lower-resolution screen 

settings may cause trouble in viewing all sections of the window, it is suggested that users set their screens to higher 

resolutions.
26

o Production Process Energy Efficiency (%)

o Pathway Efficiency (%)

o WTP Efficiency (%)

• Case Definition

• Model Information

After inspecting the results, the user may then print this results page or save it as a PDF 

document by selecting the appropriate buttons. 

Multiple results may not be viewed at the same time. To compare different cases, the user 

can either print results or download data to manipulate it according to their needs.

Downloading of data is achieved through the “Simulations” window. If the “Download” button 

is selected, the user is given the option to save the data in the format of a comma-separated value

(.csv) file, which is a file type that stores tabular data and may be viewed in Microsoft (MS) 

Excel. All data from the GDS are collected and displayed here. Users may look into this file for 

details and perform any actions to suit their needs, such as creating tables or graphs. For more 

details, see Section 4.4 (Running the MSM and Obtaining Outputs) of this document.
27

4 Operating the MSM as a Comprehensive User

Comprehensive users should be familiar with the basic user functions of the MSM before using

the comprehensive version. Comprehensive users install and run the MSM on their own 

machines instead of on the MSM server.

4.1 Getting Started

To explore the MSM in more detail and with more flexibility, comprehensive users initially need 

to contact the MSM principal investigator, Mark Ruth of NREL, at Mark_Ruth@nrel.gov to 

request the model files. In addition, the programming language Ruby is required; Windows-, 

Linux-, and Mac OS X-compatible versions are available for free download at 

http://www.rubylang.org/en/downloads/. The Ruby 1.8.6 One-Click Installer download (Figure 

13) and its default settings are recommended. Once Ruby is installed and the files received from 

the principal investigator are saved, the user may then further explore the capabilities of the 

MSM.

Figure 13. Ruby download site
28

4.2 MSM Files

MSM files are sent to the user from the principal investigator in a folder named MSM_Run, 

which should be saved in the root directory on the user’s computer. This folder contains a 

subfolder, MSM0878,

15

• cwd: No user input required. The cwd folder is used by the model when running. Users 

should note that currently, an error in running the MSM (due to MSM itself or one of the 

component models) results in files stored in this folder in the format of model.3 digit 

number.2 digit number. All files in this format need to be erased.

which contains the following subfolders (in alphabetical order):

• data: User input is optional, although great care should be taken when editing and 

opening the files. The data folder contains each of the models as well as references. 

These files are the component models (and therefore the core of the MSM model). They 

are accessed when the model is running. Any changes to the values in these files affect 

the results of the model.

Users should save a copy of the data folder in a separate location to serve as a backup, as 

files here are overwritten each time the MSM is run.

Users are encouraged to examine the model files to better understand how the MSM 

model components work. Additionally, a text file titled units_conversion_factors.txt is 

saved under the data folder, displaying common unit conversion factors.

• jobs: No user input required. Folder is currently empty.

• lib: No user input required. Folder is currently empty.

• Run_fold: This is the main folder for user input. The Run_fold folder contains the .xml

file that users can edit to run specific scenarios. The .bat file is the main application that 

runs the MSM model and requires user input. The Run_fold folder is also where the 

output files are created. It is also suggested that users save a backup copy of this folder in 

a separate location prior to initiating their runs, to make sure they have an unchanged 

version of the .xml and .bat files.

• output: No user input required. Folder is currently empty.

• scripts: No user input required. Contains two sub-folders: php (currently empty) and ruby

(contains all of the Ruby subprogram files).

4.3 User Inputs

With the Ruby software installed and all the necessary files downloaded, the user is now ready to

edit parameters to obtain results reflecting answers to issues and areas of concern specific to 

them. To accomplish this, the user has the flexibility to either edit parameters found in the .xml

file provided in the folder Run_fold or to directly make changes within the individual component 

models. These modifications are then followed by correspondingly adjusting the batch file, in 

preparation for running the MSM with user-defined inputs.

 15 The number in this folder title denotes the most recent MSM code revision number.
29

4.3.1 Editing the .xml File

To edit the .xml file (located in the MSM_Run folder), users need to open the file in an 

appropriate editor (typically MS Notepad). Please note that if the .xml is double-clicked, it will 

typically open in an Internet browser and will not be editable. The .xml file has three different 

sections, as seen in Figure 14:

1. User Data: Includes all of the inputs 

selectable in the GUI of the basic user 

version. The Ruby code does not select 

models based on inputs from here; 

instead, the user is responsible for naming 

the necessary component models in the 

“Execution Order” section.

2. Default Data: Contains many of the 

inputs into the four models that make up 

the MSM (Please note that these values 

are set to specific defaults in the basic

user version of the model, and no errorchecking will be performed by the model 

to confirm the plausibility of edited inputs 

in the default data section.). 

3. Execution Order: Shows the order in 

which the MSM calls the other four 

component models.

16

be edited only by changing the values 

This section should 

(filenames), versions, and descriptions of 

the component models.

 16 The MSM runs GREET twice. The first instance is to extract some parameters from GREET to use as inputs for 

H2A production and delivery models, and the second instance is to obtain energy and emissions results from 

GREET. 
30

Figure 14. .xml file sections
31

Editable data in the .xml file is arranged in the format of “name,” “value,” “units,” and 

“description.” Users may edit the “value” and “units” fields of each data entry, although care 

should be taken to edit only the values between the “> <“ symbols. In the example below, the 

value for “liquidTruckTotalTime” has been changed from 1 (Figure 15) to 14 (Figure 16), and 

the units were changed from days to hours. This example shows how comprehensive users can 

edit the model to match their specific situation as opposed to using the model defaults. 

Figure 15. Original units for liquidTruckTotalTime

Figure 16. New units for liquidTruckTotalTime

The following table shows all the possible unit names accepted by the program.

Table 1: Unit names

Unit Type Unit Additional Names

Area square_mile mile_square, sq_mi, sq_miles, square_miles

acre Acre, acres, Acres

hectare hectares, ha

square_feet feet_square, sq_ft, sq_feet, square_foot

square_inches inch_square, sq_in, sq_inch, square_inch

Current ampere A, amperes, amp, amps

Coded Mix coded_mix Coded_Mix, Coded_mix

Energy joule Joule, J, joules, Joules

megajoule MJ, megajoules

gigajoule GJ, gigajoules

Btu BTU, btu, Btus, BTUS, btus, British_thermal_unit, 

british_thermal_unit, britishthermalunit, 

British_thermal_units, british_thermal_units, 

britishthermalunits

mmBtu mmBTU, megaBtu, megaBTU

kWh kWhr, kWhrs, kWhour, kWhours, kwh, kwhr, kwhrs, 

kwhour, kwhours, kilowatt_h, kilowatt_hr, kilowatt_hrs, 

kilowatt_hour, kilowatt_hours

MWh MWhr, MWhrs, MWhour, MWhours, mwh, mwhr, 

mwhrs, mwhour, mwhours, megawatt_h, 

megawatt_hr, megawatt_hrs, megawatt_hour, 

megawatt_hours

GGE gge GGE
32

J H2 J_H2 J_h2, joule_h2, joule_H2, Joule_h2, Joule_H2

MJ_H2 megajoule_h2, megajoule_H2, MJ_h2

Btu_H2 BTU_H2, BTU_h2, btu_H2, btu_h2, Btus_H2, 

Btus_h2, BTUS_H2, BTUS_h2, btus_H2, btus_h2

mmBtu_H2 mmBTU_H2, mmBTU_h2, mmbtu_H2, mmbtu_h2, 

mmBtus_H2, mmBtus_h2, mmBTUS_H2, 

mmBTUS_h2, mmbtus_H2, mmbtus_h2

Kg C Kg_C

Kg_CO2 kg_co2, kilogram_CO2, kilogram_co2

lb_CO2 lbs_CO2, lb_co2, lbs_co2, pound_CO2, pound_co2, 

pounds_CO2, pounds_co2

Kg H2 kg_H2 kg_h2, kilogram_H2, kilogram_h2, Kilogram_h2, 

Kilogram_H2

Length meter m, meters

foot ft, feet

inch in, inches

mile mi, miles

km kilometer, kilometre

cm centimeter, centimetre

mm millimeter, millimetre

Light candela cd, candelas

Mass kilogram kg, kilograms

gram g, grams, gm, gramme, grammes

pound lb, lbs, pounds

ton tons, short_ton, short_tons

metric_ton mt, metric_tons

Money dollar $, dollars

None 1

% percent, per-cent, per_cent

mole_fraction Mole-fraction, mole_frac, mole-frac, mol_fraction, molfraction, mol_frac, mol-frac

fraction frac, Fraction, Frac

Power watt W, Watt, watts, Watts

kilowatt kW, kilowatts

Station station Station

Substance lbmol pound-mole

kmol Kmol, kmole, Kmole, kmoles, kilomol, kilomole, 

kilomoles, Kmoles, Kilomole, Kilomoles

Temperature kelvin K

Time second s, sec, seconds, secs

minute min, minutes

hour h, hr, hrs, hours

day d, da, days

year yr, years, y

Trip trip Trip, trips, Trips

roundtrip Roundtrip, roundtrips, Roundtrips

Truck truck trucks, Truck, Trucks

Truckload truckload Truckload, truckloads, Truckloads

Volume cubic_meter cubic_m, cubic_meters, m_cubed, meter_cubed, 

meters_cubed

cubic_foot cubic_ft, cubic_feet, ft_cubed, foot_cubed, feet_cubed

liter l, L, liters, litre, litres

gallon gal, gallons

normal_cubic_foot normal_cubic_ft, normal_cubic_feet, 
33

normal_ft_cubed, normal_foot_cubed, 

normal_feet_cubed, Normal_cubic_foot, 

Normal_cubic_ft, Normal_cubic_feet, 

Normal_ft_cubed, Normal_foot_cubed, 

Normal_feet_cubed

normal_cubic_meter normal_cubic_m, normal_cubic_meters, 

normal_m_cubed, normal_meter_cubed, 

normal_meters_cubed, Normal_cubic_meter, 

Normal_cubic_m, Normal_cubic_meters, 

Normal_m_cubed, Normal_meter_cubed, 

Normal_meters_cubed

standard_cubic_meter standard_cubic_m, standard_cubic_meters, 

standard_m_cubed, standard_meter_cubed, 

standard_feet_cubed, Standard_cubic_foot, 

Standard_cubic_ft, Standard_cubic_feet, 

Standard_ft_cubed, Standard_foot_cubed, 

Standard_feet_cubed, std_cubic_foot, std_cubic_ft, 

std_cubic_feet, std_ft_cubed, std_feet_cubed, 

Std_cubic_foot, Std_cubic_ft, Std_cubic_feet, 

Std_ft_cubed, Std_foot_cubed, Std_feet_cubed, scf

The description for some of the data items will be preceded by “Allowable Values” that include 

ranges or specific values that the model needs to run properly (Figure 17).

Figure 17. Display of “Allowable Values” for data items

When a user is finished changing the MSM model inputs, the file should be saved as 

filename.xml (“filename” used for example purposes only). It is important that the .xml extension 

be used here.

4.3.2 Editing the Component Models of the MSM

Users may edit values in the MSM component models, but, as stated before, great care should be 

taken. It is recommended that users save an original copy of any of the models that are edited.17

 17 Especially note that when using GREET, the “undo” button does not restore the model to its previous state.

Because the MSM adjusts inputs to the component files, the user should adjust only inputs that 

the MSM will not overwrite. Also, the cell locations or names should not be modified because 

this could affect the operation of the MSM.
34

Before opening the models from the data subfolder, users first need to confirm settings within 

MS Excel 2003 (Figure 18). Users should click the “Tools” heading, then click “Options” from 

the drop down menu, and finally select the “Calculation” tab on the “Options” pop-up box. Users 

need to confirm that “Calculation” is set to “Manual,” and the “Iteration” box should contain a 

check.

Figure 18. Window to confirm MS Excel 2003 settings

Many of the models contain macros, so users may need to adjust their macro security level. 

Users should select either a “Medium” or a “Low” security level from the Macro security pop-up 

box located in “Tools”“Macros”“Security” (Figure 19). After these settings are in place, 

users may open and edit the separate models.
35

Figure 19. Steps to adjust macro security

4.3.3 Editing the Batch File

The .bat file, also located in the MSM_Run folder, is an executable batch file that will run the 

MSM automatically. In order to reflect the changes made to the inputs (either via the .xml file or 

the individual component models), users need to also adjust the .bat file. However, this file will 

run the MSM automatically if double-clicked; therefore, to open the .bat file for editing, users 

need to right-click the .bat file and select “edit.” The .bat file will then open in the user’s default 

editor (typically MS Notepad). In the batch file, users need to edit only the filenames of the .xml

(input file), .csv (output MS Excel file), .xml (output chart), and .txt file (output log). Filenames 

should be no longer than eight characters. The results files need to be on the same line as the 

Ruby command (Figure 20). Note the beginning of the command is ruby run_maestro.rb, and the 

end is filename_log.txt.

After the user has edited the filenames, the .bat file should be saved with a new name. To save 

the new file as a batch file, the user should type in the “File name:” box of the “Save As”

window filename.bat (“filename” is an example; users should create unique names for their 

scenarios) and select “All Files” from the “Save as type” drop-down menu, as seen in Figure 20. 

Otherwise, the file will be saved as the same type of file as the user’s editor (i.e., a .txt file for 

users editing with MS Notepad).
36

Figure 20. Window used to change filenames of edited files

4.4 Running the MSM and Obtaining Outputs

Once the desired changes to the model inputs are made, the user is then ready to run the model.

Please note that any documents that are open in MS Excel at the time should be saved 

and closed before running the model. Failing to do so may result in these MS Excel files 

being closed without being saved when the model runs, resulting in loss of previous 

work.

To run the model, the user needs to simply double-click the user-created .bat file, and the model 

will begin running in a new window (typically a DOS command prompt), as shown in Figure 21. 

The text in the command prompt is stored as an output and is located in the log file output.
37

Figure 21. MSM running in a command prompt

The log file provides users with three forms of outputs, allowing users details and flexibility in 

utilizing the outputs to suit their analysis needs:

1. output.csv: This output is in the format of a comma-separated value (.csv) file, which is a 

file type that stores tabular data. It can be opened in MS Excel. All data from the GDS are

collected and displayed here with all values in the MSM’s proper units. The MSM’s 

proper units and the unit values are kept within the MSM and are kept consistent in order 

to simplify MSM calculation. The user may look into this file for details sought and 

perform any actions to suit their needs, such as creating tables or graphs. Sample entries 

from the output.csv file are shown in Table 1.

2. chart.xml: This file can also to be opened in MS Excel and contains a subset of the output 

in the output.csv file. However, in some cases the values are displayed in a different set 

of units than those in the output.csv file. The values and units match those on the results 

screen shown in the web applications. The proper units are also displayed, thereby 

allowing the user to observe when the values and units used are different than those in the 

output.csv file.

3. log.txt: This is a text file that can be helpful to users in de-bugging the model. It displays 

the execution order, data used, and all other relevant details regarding the operation of the 

MSM in a step-by-step fashion, thus serving as a guide to users in deciphering details if 

faced with problems or aiding them in understanding the process better (see Figure 22).

Table 1 includes sample entries from the output.csv file. The “Variable Name” column shows the 

name of the variables used by the MSM model. The “Value,” “Units of Output,” and “Proper 

Units” columns provide the actual values and units resulting from the model scenario set up by 

the user. The “Variable Description” column displays brief information about each variable. The 
38

“Source Model” column shows where each variable’s value is generated. The four models—

HyArc, HDSAM, H2A Production, and GREET—are represented in addition to values specific 

to the MSM model. The default data entries are variables that are MSM defaults and can be 

changed only in the .xml file of the comprehensive user model. The user input entries are 

variables defined by the user when setting up specific scenarios. Finally, the GDS script entries 

are variables generated by the MSM model run.

Table 2. Sample entries from the output.csv file

Variable Name Value Units of 

Output Variable Description ProperUnits

Source 

Model

bituminousCoalLHV 26,100,117 joule / 

kilogram

Bituminous coal (as 

received)

joule / 

kilogram HyARC

cityH2ProductionRequirement 18,685,863 kg/yr City hydrogen production 

required before losses

kilogram / 

year

GDS 

script

cityH2Use 18,685,863 kilogram / 

year City hydrogen use kilogram / year

HDSAM

co2SeqBitumCoal 0.9 1 CO2 sequestration in coal 

case

1 Default 

data

deliveryMode None How hydrogen is delivered 

to forecourt User input

productionCapacityFactor 0.7 1 Production capacity factor 1 H2A 

Production

poplarFarmingEnergyUse 272,812.2 joule / 

kilogram Poplar farming energy use joule / kilogram GREET

Figure 22. Sample log.txt file

4.5 Running the multi parameter option with MSM

The multi parameter run gives the comprehensive user an option to insert multiple values into the 

input.csv file’s various inputs. This file is referred to as the parameter schedule. The MSM runs 

an amount of times that is in accordance with this schedule. This option is often used to give the 
39

MSM different distribution values. Below is an example of a parameter schedule file with five 

sets of values. The MSM will run five times with each run using a set (row) of numbers from the 

schedule.

Figure 23. Sample parameter schedule file

The users can input their own sets of values into the schedule file. Often, values will be put in 

according to Monte Carlo distributions with X sets reflecting X iterations of a simulation. The 

model would then run the X sets of values through and provide the same number of output sets.

1. To make a multiparameter run, the following additional files are needed:*18

paramSched.csv

batch_methods.rb

create_batch.rb

pre_start.rb

pre_run.rb

after_run.rb

2. The second step is to make sure that the auto-recovery option in Excel is turned off. 

A. In the .xml file, scroll to the end and see which models are being used for this 

process (i.e., GREET Model 1.8B downloaded 080317.xls).

B. Make the following changes to every model listed in the .xml file:

i. Go to tools  options.

ii. Click on the “save” tab.

iii. Uncheck the “automatically save” option.

iv. Check the lower “disable auto-recovery” option.

v. Save the excel file.

 18 Some of these file names are defined in batch_methods.rb, and it is not recommended to modify them.
40

Figure 24. Options menu

3. Edit the paramSched.xls file to as many parameters as needed. The user might choose

@Risk to create a stochastic set of variable input parameters.

4. Now the program is ready to run.

A. Go to the CWD directory in the command prompt.

B. In the command prompt, type “ruby create_batch.rb.”

C. In the command prompt, type “batch_MSM.bat.”

4.6 Using the Autotest Feature

The autotest feature allows comparison of versions (or even small modifications) of the MSM. 

Autotest compares the outputs of the currently running MSM version to a set of validated 

outputs. The comparison is done automatically with minimal user interference for the entire 

chosen set of inputs. 

To run the autotest.rb, a separate directory should be created, containing a set of input.xml and 

corresponding output.csv files. Typically, the set of input.xml files represents the array of 

production technologies with delivery options of interest, and output.csv files are created by a 

validated MSM version using these input files. To have autotest working properly (and to avoid 

confusion), the corresponding pairs of input.xml and output.csv should have the same name with 

different extensions (e.g., distributedSMR.xml and distributedSMR.csv).

Figure 25. Example of directory structure for running autotest
41

In this example, the Ruby scripts (including autotest.rb) are located in the ruby directory, and the 

set of input.xml and corresponding output.csv files are located in the testing directory. The 

autotest.rb should be called from work directory cwd, and the command should include the path 

to testing directory as a parameter:

ruby ..\scripts\ruby\autotest.rb ..\testing

This command will display the differences from the standard output, or “The output matches the 

given output” will be displayed if there are no differences found.
42

5 Conclusion

As presented and detailed in this document, the MSM is a valuable tool that provides an 

overarching view of different aspects related to the transition to a hydrogen economy. It 

accomplishes this by linking various detailed models, each offering a unique level of detail and 

perspective. Future plans regarding expansion and enhancement of the MSM will aid the 

dialogue among the members of the analysis community and will provide a simplified and 

integrated tool to better understand the possible pathways to a hydrogen economy.
F1147-E(10/2008)

REPORT DOCUMENTATION PAGE Form Approved

OMB No. 0704-0188

The public reporting burden for this collection of information is estimated to average 1 hour per response, including the time for reviewing instructions, searching existing data sources, 

gathering and maintaining the data needed, and completing and reviewing the collection of information. Send comments regarding this burden estimate or any other aspect of this 

collection of information, including suggestions for reducing the burden, to Department of Defense, Executive Services and Communications Directorate (0704-0188). Respondents 

should be aware that notwithstanding any other provision of law, no person shall be subject to any penalty for failing to comply with a collection of information if it does not display a 

currently valid OMB control number.

PLEASE DO NOT RETURN YOUR FORM TO THE ABOVE ORGANIZATION.

1. REPORT DATE (DD-MM-YYYY)

Revised July 2009

2. REPORT TYPE

Technical Report

3. DATES COVERED (From - To)

4. TITLE AND SUBTITLE

Hydrogen Macro System Model User Guide, Version 1.2.1

5a. CONTRACT NUMBER

DE-AC36-08-GO28308

5b. GRANT NUMBER

5c. PROGRAM ELEMENT NUMBER

6. AUTHOR(S)

M. Ruth and V. Diakov: NREL

T. Sa and M. Goldsby: Sandia National Laboratories

K. Genung, R. Hoseley, A. Smith, and E. Yuzugullu: SENTECH, Inc.

5d. PROJECT NUMBER

NREL/TP-6A1-44799

5e. TASK NUMBER

HS071003

5f. WORK UNIT NUMBER

7. PERFORMING ORGANIZATION NAME(S) AND ADDRESS(ES)

National Renewable Energy Laboratory

1617 Cole Blvd.

Golden, CO 80401-3393

8. PERFORMING ORGANIZATION

REPORT NUMBER

NREL/TP-6A1-44799

9. SPONSORING/MONITORING AGENCY NAME(S) AND ADDRESS(ES) 10. SPONSOR/MONITOR'S ACRONYM(S)

NREL

11. SPONSORING/MONITORING

AGENCY REPORT NUMBER

12. DISTRIBUTION AVAILABILITY STATEMENT

National Technical Information Service

U.S. Department of Commerce

5285 Port Royal Road

Springfield, VA 22161

13. SUPPLEMENTARY NOTES

14. ABSTRACT (Maximum 200 Words)

The Hydrogen Macro System Model (MSM) is a simulation tool that links existing and emerging hydrogen-related 

models to perform rapid, cross-cutting analysis. It allows analysis of the economics, primary energy-source 

requirements, and emissions of hydrogen production and delivery pathways.

15. SUBJECT TERMS

User guide; Hydrogen Macro System Model; MSM; cross-cutting analysis; hydrogen production; hydrogen delivery 

pathways

16. SECURITY CLASSIFICATION OF: 17. LIMITATION 

OF ABSTRACT

UL

18. NUMBER 

OF PAGES

19a. NAME OF RESPONSIBLE PERSON

a. REPORT

Unclassified

b. ABSTRACT

Unclassified

c. THIS PAGE

Unclassified 19b. TELEPHONE NUMBER (Include area code)

Standard Form 298 (Rev. 8/98)

Prescribed by ANSI Std. Z39.18