Personal tools
You are here: Home → BlueSky Framework → Running BlueSky for the First Time
BlueSky Framework

USFS LogoNational Fire Plan logoNASA logoJoint Fire Science Program LogoEPA logoBlueSky is a framework for model management. It facilitates the use of predictive models that simulate the cumulative impacts of smoke on air quality from forest, agricultural, and range fires.

BlueSky is maintained by the U.S. Forest Service AirFire Team and Sonoma Technology, Inc.
AirFire LogoSonoma Technology, Inc. Logo

 

Running BlueSky for the First Time

— last modified Jul 30, 2009 04:37 PM

How to run BlueSky locally the first time.

Collecting input data

Before running the BlueSky Framework, you need to collect your input data.  At a minimum:

  • Determine the date(s) for which to run a simulation
  • Find a source of fire information (activity data) for the selected dates
    • This can either be an operational source like SMARTFIRE or a CSV file you prepare manually
  • Find a source of weather information (meteorological data) for the selected dates
    • This is only required if you want to simulate smoke dispersion or trajectories

If you plan to use SMARTFIRE input data, make sure you have a valid username and password for access to the SMARTFIRE server.

Configuring BlueSky for the first time

The first time you run BlueSky, it can be helpful to create a user-specific configuration file.  If you create a file called ".bluesky" in your home directory, you can specify any user- or site-specific preferences here.  In particular, it can be useful to configure:

  • SMARTFIRE username and password (default is to prompt interactively)
  • Path to meteorological data files (default is $BS_DIR/input/met)
  • Path to input fire data (default is $BS_DIR/input/fires)
  • Any other user-specific preferences

 

An example .bluesky file is shown below:

[DEFAULT]
MET_DIR=/net/pinot/data/NASA-BSR/MM5/Run
INPUT_DIR=${BS_DIR}/input/fires

[InputSMARTFIRE]
USERNAME=dpryden
PASSWORD=xxxxxxx

Configuring your BlueSky run

To set up for your BlueSky run, you need to select a model pathway and any configuration options.  A number of predefined setup files (.ini files) are included with the framework, under the $BS_DIR/setup directory.  You can either use one of these as-is or customize to suit your needs.  A good starting point for customization is the example.ini file, which looks like this:

#******************************************************************************
#
#  BlueSky Framework - Controls the estimation of emissions, incorporation of 
#                      meteorology, and the use of dispersion models to 
#                      forecast smoke impacts from fires.
#  Copyright (C) 2003-2006  USDA Forest Service - Pacific Northwest Wildland 
#                           Fire Sciences Laboratory
#  BlueSky Framework - Version 3.1    
#  Copyright (C) 2007-2009  USDA Forest Service - Pacific Northwest Wildland Fire 
#                      Sciences Laboratory and Sonoma Technology, Inc.
#                      All rights reserved.
#
# See LICENSE.TXT for the Software License Agreement governing the use of the
# BlueSky Framework - Version 3.1.
#
# Contributors to the BlueSky Framework are identified in ACKNOWLEDGEMENTS.TXT
#
#******************************************************************************

[META]
#
# The graph file that describes how the models interconnect
#
includes=${GRAPH_DIR}/default.graph
#
# The input tasks we're going to run to read in our input data
#
inputs=$MET StandardFiles SMARTFIRE
#
# What step accepts the input data from the input(s) above
#
start=$EXTRACT_LOCAL_MET
#
# The step(s) we are trying to accomplish -- the "stopping point" on the graph
#
targets=$DISPERSION
#
# What output tasks to run once we've reached our stopping point
#
outputs=StandardFiles SMOKEReadyFiles KMLAnimation MapImages

[DEFAULT]
#
# Analysis time range (override with -d and -H command-line switches)
#
DATE = 2009040100Z
HOURS_TO_RUN = 48

#
# What models are we going to run to get those outputs?
#
MET=MM5
EXTRACT_LOCAL_MET=MM5LocalMet
FUEL_LOAD=FCCS
TIME_PROFILE=FEPSTimeProfile
EMISSIONS=FEPSEmissions
PLUME_RISE=WRAPPlumeRise
DISPERSION_MET=CALMET
DISPERSION=CALPUFF
TRAJECTORY_MET=MM5ToARL
TRAJECTORY=HYSPLIT

#
# Growth models (by fire type)
#
WILDFIRE_GROWTH=Persistence
PRESCRIBED_GROWTH=NoGrowth
OTHER_GROWTH=NoGrowth

#
# Consumption models (by fire type)
#
WILDFIRE_CONSUMPTION=CONSUME
PRESCRIBED_CONSUMPTION=CONSUME
OTHER_CONSUMPTION=CONSUME

#
# Consumption canopy fraction (by fire type)
#
WILDFIRE_CANOPY_FRACTION = auto
PRESCRIBED_CANOPY_FRACTION = 0.0
OTHER_CANOPY_FRACTION = auto 

# 
# Other run-specific options (overrides $BS_DIR/base/etc/defaults.ini)
#
HOURS_TO_RUN_TRAJECTORY = 12
SPIN_UP_EMISSIONS = true
DISPERSION_OFFSET = 0
STOP_IF_NO_BURNS = true
STOP_IF_NO_MET = true

Any option set in the .ini file can be overridden in your .bluesky file, if desired.  Any option not specified in the .ini file is taken from the defaults.ini file, located at $BS_DIR/base/etc/defaults.ini.

Running BlueSky

Once you've selected or edited a setup (.ini) file, simply specify the name of the setup file on the command line.  For example, to run the "example.ini" configuration, type:

bluesky example

If you've copied the file to another location (for example, to your home directory), you can give the full path instead:

bluesky /home/dpryden/example.ini

BlueSky also accepts a large number of command-line options.  To see the list of available options, run

bluesky -h

Two useful options are -d and -H, which allow you to override the starting date and length in hours of your analysis time range.  This is particularly useful if you want to run similar simulations for different days over a longer time period.

BlueSky outputs

All output files from a BlueSky run will be placed in the directory named by the $OUTPUT_DIR configuration variable.  If this is not specified, the default is to create a new folder under $BS_DIR/output named YYYYMMDDHH.N, where YYYY is the year, MM is the month, DD is the day, and HH is the hour (UTC) of your analysis start date, and N is a unique number for this run.  So the first run you do for 2009-07-16 will produce output in $BS_DIR/output/2009071600.1, the second will produce output in $BS_DIR/output/2009071600.2, and so forth.

Depending on the models you selected to run, you will get the following files in the output directory:

  • archive-YYYYMMDDHH.tar.gz
    Tarball archive containing various intermediate data files, detailed logs, and other information.

  • summary.txt
    Short text file describing the models used to produce the output data.

  • fire_locations.csv
    CSV file containing total emissions and other data for each fire location (burning point) for each day of your analysis period.

  • fire_events.csv
    CSV file containing summarized emissions and other data for each fire event (group of fire locations) defined in the input data.

  • fire_emissions.csv
    CSV file containing emissions and other data for each fire location, for each hour that the fire was modeled.

  • ptinv-YYYYMMDDHH.ida
    pthour-YYYYMMDDHH.ems95
    Point-source inventory files designed for use with the S.M.O.K.E. model.

  • smoke_dispersion.nc
    Hourly smoke (PM2.5) dispersion model results in NetCDF format.

  • dispersion_YYYYMMDDHH.png
    Hourly images of smoke (PM2.5) dispersion model results

  • smoke_dispersion.kmz
    Hourly smoke (PM2.5) dispersion model results, packaged for viewing with Google Earth or comparable tools.

What if something went wrong?

Although we strive to make the BlueSky Framework easy to use, simple to configure, and reliable in operation, sometimes things do go wrong.  Usually, though, the following steps can help to resolve the issue:

  • Did the framework provide an error message describing the problem?  For help in understanding how BlueSky formats error messages, see the understanding an error page.
  • Are your input files correctly formatted?  Incorrectly named CSV column headers or incorrectly quoted character data in CSV files can be the source of problems.  BlueSky uses the same parsing rules for CSV files as Microsoft Excel; if Excel doesn't open your CSV file correctly, chances are BlueSky won't either.
  • What was BlueSky working on when things went wrong?  If the normal framework output isn't detailed enough to understand what BlueSky is doing, try running with the -v switch (or even -vv) to increase the verbosity of the console log.
  • Did BlueSky abort the run, or did the run finish normally, albeit with incorrect results?  If BlueSky aborted the run, then there will be a directory under $BS_DIR/working that contains additional log files and intermediate data files.  If the run finished normally, these same files will have been archived in the "archive-YYYYMMDDHH.tar.gz" file in the output directory.
  • If you're still stuck, you can contact the BlueSky Framework team for support, and we will help as best we can.
Document Actions