IV. SIP/SOLAR2000 USER GUIDE SIP/SOLAR2000 Professional Grade V2.37 hybrid solar irradiance model ================================= SYSTEM REQUIREMENTS: The SIP/SOLAR2000 Professional Grade V2.36 solar irradiance model is a binary IDL save file that runs with a Graphics User Interface (GUI). Any platform that has licensed Research Systems, Inc (RSI) Interactive Data Language (IDL) version 6.3 or higher can use this model. However, if it is run from the downloaded self-extracting package, Users of the SIP/SOLAR2000 PG model must also have Java v1.4 or higher running on their system and an internet connection in order to obtain forecast data. IDL VIRTUAL MACHINE USERS: Starting with SIP/SOLAR2000 v2.23 and IDL 6.0 or higher, it is possible to run the model on any platform without an IDL license. The IDL VM is available via free download from the ITT web site. You will need to login or register as a new user at: http://www.ittvis.com/Login Once you are logged in, visit the IDL Virtual Machine webpage for general information: http://www.ittvis.com/ProductServices/IDL/VirtualMachine.aspx To download the IDL Virtual Machine, visit the ITT Visual Information Solutions at: http://www.ittvis.com/Downloads/ProductDownloads.aspx You will need to download the entire IDL 7.x Product (not the License Server) appropriate to your operating system. It is downloaded as a compressed *.tar.gz file, so depending on your operating system, you will need to uncompress it. For example, double-click it, use a zip/unzip application, or for Linux/Unix systems, see the man page for gzip, unzip, or tar (e.g., unnzip -x *.tar.gz, tar -xf *.tar). Be sure to decompress the IDL 7.x product into a working directory you will find easy to work with in subsequent uses (e.g., /apps/itt). ------------------------------------------------------------------------ For a Linux/Unix installation, first set up couple of environmental variables. 1. For example with a Korn or Borne shell login, edit the .bashrc, .cshrc, or equivalent: export IDL_DIR=/topdir/idl71 ... whatever directory path to the idl installation, just above it's bin directory for a C-shell: setenv IDL_DIR /apps/itt/idl71 2. then, create an alias to idl, e.g. in the Borne or Korn shells: alias idl="/topdir/idl71/bin/idl" for a C-shell, use: alias idl /topdir/idl71/bin/idl 3. You may need to set your environment to include your SIP working directory, e.g. export PATH=$PATH:/home/user/SIP/SIPPGv237 4. Logout and log back in. Confirm it works by typing: idl ...IDL should start up in demo mode. Type exit to get out of the IDL demo mode. 5. Change your working directory to where you have SIP installed, then type: idl -vm=sip_vm.sav Mac users: a X-terminal window must first be opened. (Please note that there is a space between "idl" and "-".) If you type simply: idl -vm An IDL window will present you with a menu to navigate to the siv_vm.sat file You should be ready to run SIP through its GUI at this point. --------------------------------------------------------------------------------- Windows NT and XT users: drag and drop the S2K sip_vm.sav application onto the IDL VM icon to activate the program. --------------------------------------------------------------------------------- DOWNLOAD INSTRUCTIONS FOR THE SOLAR IRRADIANCE PLATFORM (SIP): 1. At http://SpaceWx.com, click on "Products -> SIP", or go directly to: http://www.spacewx.com/solar2000.html, and select the "Download and Install SIP" link. 2. Register for updates with your name, email address, institution and company.. 3. Click "Submit". 4. Your Browser will display the link to an anonymous ftp directory, which will contain files and/or subdirectories. Navigate to the version of SIP you desire (e.g., SIP_Professional_Grade). 5. Click on the sip_v2_37.zip file to begin the download, saving it to a directory of your choosing. Note: If your Browser fails to work as described above, simply use an FTP application or command, e.g., ftp sol.spacenvironment.net and use a binary "get" command. The username is spcusr, and the password is usrspc 6. Decompress the zip file. Some Windows and Mac computers are already set up to decompress the file if you simply double-click or right-click on the sip_v2_37.zip file. You may want to place the new SIP folder in the desired subdirectory or folder on your computer. Alternatively you might use the "StuffIt Expander" decompression application which is widely available. For Linux/Unix users, see the man page for gzip, unzip (e.g., unzip -x SIPPGv237.zip) 7. Read the s2k_readme text file, which contains the license agreement and IDL SIP instructions for running the model. Additional Notes: For Windows VISTA: a. See comment in SIP v2.37 notes. For Windows 98/NT/XT/XP: a. Move to any folder/directory as a default (e.g., SOLAR2000PG_v2_37) which will contain all the files that will be necessary to run SIP. You may need to create this folder: it will serve as the default IDL working directory to run SIP. b. Open a Zip application, e.g., Aladdin StuffIt Expander. If you don't have a Zip file application, they are widely available on the Internet. c. Unzip the downloaded zip file. Depending on the application, this may be a two-step process. Note: Because of the wide variety of decompression applications, you will need to follow the instructions provided with the application. d. All the necessary files should be should be created under an additional SIP subdirectory. You may want to rename or move this subdirectory with all it's files to another location of your choosing. Be certain you have full read/write/execute privileges to all the files. e. Read the s2k_readme text file, which contains the license agreement and IDL SIP instructions for running the model. DIFFICULTIES? If you are having difficulty installing SIP, you may need 4 applications: (1) A terminal window application (2) A file decompression application (3) An FTP application (4) An X-windows application Fortunately, nearly all these applications can be found, for free, at: http://www.download.com/ (1) A Terminal window is most probably already on your system and you will likely find it in your Applications/Programs folder with a "Terminal" or "Console" name. It is the bare-bones text-only application that just opens a window for typing in commands. It is from this window you can perform basic commands to ftp to a server, unpack compressed files, start SIP/SOLAR2000, etc., but without experience in doing so you will not find it very helpful. Some of the mysteries of using text-based commands can be found in a number of "how-to" books at your local computer store. (4) An X-window application may necessary to display the plots and graphics the IDL VM needs. It has been around the science community for some time, with it's origins in Unix, providing a common set of tools. It can also be found at http://www.download.com/, but you will find it a bit complex in getting started. There is a fairly expensive application that has an integrated Window interface (Do a web search on "Hummingbird X-windows"). However, it does come with a terminal window, ftp, etc. applications that should allow you to start SIP. You will find getting all this started may have a fairly steep learning curve, but these are fairly common applications necessary for most space-science applications (IDL is the most commonly used programming language in the space-weather community), and having these tools will prove to be useful later on. RUN INSTRUCTIONS: 1. Start an IDL session (IDL v6.3 or higher). THE DEFAULT DIRECTORY "Space_Environment_Technologies" THAT MUST BE SELECTED IN THE IDL APPLICATION IS THE FOLDER OR SUBDIRECTORY THAT CONTAINS THESE DOWNLOADED FILES. 2. Double-click the "launch_sip" icon (If you already have IDL installed, you can start a terminal session, and type "sip" at the command line in IDL). The model will start and you will see the SIP GUI appear in a separate window. Some platforms are case-sensitive in IDL (e.g. UNIX systems) so please note the lower-case characters. 3. To run the SIP application (it can only be run through the GUI), select the desired input parameters from the left-side list menus (5 menus): a. Start year [1947-2001] b. Start day of year [1-366] (Note: only leap years have 366 days; if day 366 is used for a non-leap year, the program defaults to 1980-366 as the start day and "invalid starting date" is printed in the IDL output log.) c. Number of days to model [1-1000] (Note: some computers may have limited memory and will not run 1000 days at a time; if this is the case, either increase the computer memory allocated to IDL or run a smaller number of days.) d. Spectral format [indices only, 1 nm bin size full solar spectrum, 39 EUV lines and wavelength groups in the EUV91/EUV97 format, 809 EUV 1 Angstrom lines in the SC#21REFW format. NOTE: the energy flux totals in the 1 nm bin and 809 wavelength bins will not equal each other since the 1 nm flux value is created proportional to the photon flux value divided by the center of the wavelength bin while the 809 flux value is created proportional to the photon flux value divided by the 1 Angstrom wavelength value from SC21REFW. This algorithm may be changed in a future upgrade.] e. Flux units [SI (W m-2), photon flux (photons cm-2 s-1), energy flux (ergs cm-2 s-1)] (Note: all wavelength units are in nm and the +-1 sigma uncertainties for each wavelength are listed. Currently, the value of 1.00 is used as a placeholder for this field in the 1 nm and 39 wavelength group formats. The delta-lambda unit for the fluxes is determined by the bandpass in each wavelength format.) 4. Click the "Run" button. THE RUN BUTTON MUST BE CLICKED FOR EACH NEW SETTING OF THE LISTS IN ORDER TO CREATE A NEW MODEL RUN. After a short time, you will see several panels of plots in the GUI window. At this point, the application has run the modeled irradiances for the input parameters that were selected. In the same folder as the application, you will find 3 new files: s2k_output.txt - a text file of irradiance or indices data. This file is accessed from the GUI through the "S2K Output" button; the text can be selected, copied, and pasted into another application or the file can be opened separately as a text file. s2k_tsi.txt - a text file of the solar irradiance spectrum (1 nm bins) for the first day of the run. This file is accessed from the GUI through the "S2K spectrum" button. s2k_plot.jpg - a JPEG picture file of the same data displayed in the GUI window for this run of the model. The 3 rows of plots include: TOP ROW: Integrated solar spectrum (left), coronal input in F10.7 units (center), and chromospheric input in Lyman-alpha (or Mg II cwr reported in Lyman-alpha units) (right); MIDDLE ROW: first day solar spectrum in SI units in 1 nm bin (left) and first day soft X-ray/EUV spectrum through Lyman-alpha in SI units in 1 nm bins (right); BOTTOM ROW: comparison of the F10.7 (dash line) and E10.7 (dotted line) proxies for the time period Selected (day 0 is the starting date). 5. You may print your S2K Output file to a local printer or a PS file if that is an option of your printer with the "Print" button. 6. You may click the "About S2K" button to read the LICENSE AGREEMENT, SOLAR2000 PUBLICATION ACKNOWLEDGEMENT, SOLAR2000 RELEASE NOTES, and the SOLAR2000 USER GUIDE (this document). 7. You may click the SET Sun-Planet logo to view the "About SpaceWx" text file containing general information about SpaceWx. 8. To quit the SIP application. click the "Quit" button. FREQUENTLY ASKED QUESTIONS (FAQ): QUESTION: ANSWER: 1. If the SOLAR2000 Research Grade V2.37 The GUI is being asked to display GUI application is run with a number invalid dates and/or indices and of days to model that extends past the the program must be restarted. In last valid date (see item 7.b above), this case, simply exit IDL, start the program will ungraciously stop. a new IDL session, and restart the Why? GUI, taking care to not run the model past the last valid date. 2. If the "Print" button on the GUI is The file "s2k_plot.tif" is the used for printing the plot file the default plot file and is fully right-hand border of the displayed displayed with graphic software. plot may not be reproduced. Is there Other print options include using another solution for this? the cursor to click and highlight one of the three plot panels then print that panel from IDL. Another alternative is to highlight a panel, copy the plot panel contents into the computer's internal buffer or 'clipboard', then paste, print, and/or save the graphic within a graphics program. 3. IDL, in this GUI application, does Set the monitor to 8-bit or, as an not properly display colors if the alternative, 24-bit color. monitor is set to 16-bit color. Why? 4. I would like to have the capability This capability is being developed. of using a callable IDL subroutine It will be possible to use this as module rather than a GUI. This a special subroutine in the future. would serve better in an IDL or Fortran routine that needs solar irradiances updated in by a time step. Can you provide this? 5. I would like to have the model This capability is planned for a extended to shorter wavelengths and future upgrade of SOLAR2000. higher energies in the X-rays (0.05 - 1.8 nm). When will this be available? 6. There is a discontinuity for E81 This artifact was minimized in v1.16 values between the beginning of one by using an 81-day convolution. How- time frame run and the end of a ever, a user is advised to create a previous run. How do I remove this? data set of desired length and to use his or her own smooth algorithm. 7. Some of the highest resolution The SC21REFW format is used for the wavelengths in the 809 template are 809 wavelength bin format and this not uniform in grid-spacing and are format does not have uniform spacing repeated. Is this correct? between the lines. In addition, some values may appear to be repeated, e.g., 6.63 nm, but is a result of truncation of finer resolution lines (6.630 Fe XII and 6.637 Fe XVI). The v1.21 upgrade changed the lines to be reported with 3 decimal places to avoid this truncation confusion. 8. How do I find the uncertainty in The 1 sigma error of reported the irradiances and how is it instrument measurement error plus calculated? linear regression uncertainty can be found as a fraction (1.0 = 100%) in the 809 wavelength (highest resolution) listing. In the other listings, there are placeholders right now. However, since they are all coarser resolution than the 809 listing, a simple wavelength bin- average would be acceptable. A future version will incorporate the 1 sigma error for all formats. 9. Is it possible to get irradiances Yes, there are system, operational, closer to the current epoch, nowcast, and professional grade SOLAR2000 or forecast irradiances in addition versions that produce all these to the Research grade version? irradiances. For more information, including high time resolution data, please contact SpaceWx or visit the products and services link at http://SpaceWx.com. Additionally, NOAA/SEC hosts the daily nowcast SOLAR2000 irradiances on their server at http://sec.noaa.gov. 10. Can I retrieve SOLAR2000 products E10.7 and Lyman-alpha are available without using IDL? for 5 solar cycles at the products links at http://SpaceWx.com. These are daily historical data for Research use. Current epoch, daily irradiance products are also provided at that web site location. In the second half of 2003, SET plans to release historical 3-hourly data sets as well as forecast data sets, both of which will be provided for a fee. 11. Why doesn't the S(t) value of the The solar integrated spectrum (often SOLAR2000 output match the variability referred to as S(t) in SOLAR2000 in the total solar irradiance (TSI)? literature) is only variable between 1-122 nm in versions 1.yz. It is the integrated spectrum and will in- creasingly become the same as the variable TSI in versions 2.yz, 3.yz, and 4.yz. In version 2.yz, the spectrum is variable between 1-420 nm but does not include irradiance deficit due to sunspots. 12. Why are there double entries for The ASTM-E490 placeholder spectrum some of the wavelengths longwards of was used in earlier versions and had Lyman-alpha? a problem of double entries. That placeholder spectrum was upgraded to the officially released version of the reference spectrum starting with SOLAR2000 version 1.24. 13. Why is the value of E10.7 in older As the accuracy and precision of the model versions different from the EUV wavelengths are improved in v2.21 release? Model releases, the value of E10.7 will change since it is the inte- grated 1-105 nm EUV energy flux and the latter changes. As measurements improve through time, the value of E10.7, though changing, will more and more approach a fixed level for given solar conditions. For example, the 1-sigma E10 v1.15:v1.24 ratio is 6.15% while v1.20:v1.24 is 0.38%. See the discussion in version 2.21 release related to "Known differen- ces..." items 3 and 4. We have identified a process to create a "standard" by which to judge E10.7 and all other integrated irradiance proxies and work is progressing to create this standard. Our AFRL colleagues will create a several solar cycle derived F10.7 from an ensemble of satellite drag data and this independent measure of what the general level of solar flux should have been will be used to evaluate future E10.7. 14. Is there a Fortran version of A Fortran version of the model is SOLAR2000 available? not under development since most of our efforts are going into improve- ment in various spectral ranges. However, current and selected hist- orical data files are available at the http://www.SpaceWx.com web site. Also, the http://SpaceWx.com web site points to links with older EUV models that are written in Fortran. 15. Are the plotted values correct in No, the units are high by a factor the v2.21 GUI window, row 2, panel of 1E3. A typo in the v2.21 plot (e) (EUV spectrum)? module uses the energy flux rather than SI units as in row 2, panel (d). This has been corrected in v1.24a, v1.25, and versions after v2.21. 16. Which exospheric temperatures are In all versions except for v2.21 being shown in the Tinf column of these are the daytime average the S2K_output.txt file? exospheric temperature. They are not the subsolar point temperature as has been reported earlier since a cos(72) (72 deg is the angle between local atmosphere normal vector and the Sun-line vector) is used in the physics-based 1DTD model. This angle was selected because the 1DTD temp- eratures and neutral densities for 1976-200 (SC21REFW) and 1979-050 were very close to the MSIS-86 output for those dates. In addition, this angle provides an average daytime exospheric temperature for 6 years (Jan 1 1996 - Dec 31 2001) that is 1.3 times the J70 nighttime minimum exospheric temperature for the same period. The 1-sigma variation about this average temp- erature is +/-6.4%. Altogether, these point to a self-consistent exospheric temperature for input spectral solar flux. 1DTD does not use the E10.7 integrated irradiance proxy but uses the 39 wavelength groups and lines that are common in aeronomy. In v2.21, a conversion was applied to the temperatures to produce an absolute value very close to J70 nighttime minimum exospheric temperatures. We have decided not to use this conversion in all other releases of this Tinf parameter. 17. Is there a SC21REFW type of template We plan to extend the current for wavelengths between 121.5 and SC21REFW type of wavelength temp- 199.5 nm? late into this spectral region in an upcoming release of the model. 18. Why are there slight differences in The S2K PG proxy file is generated the output numbers between the RG on an operational server and will and PG model versions? have slightly different values for either the F10 or Ly-a and/or their 81-day smoothed values. This will translate to small output differences in the integrated irradiance proxies since the data on the server is continually being updated and may also be running with a different version of S2K. MESSAGES AND ERRORS: All messages and errors that occur while running the SIP application will appear in the IDL Output log which is often a separate window on many platforms. While we have done our utmost to provide a robust, validated, and rigorously tested product, WE ARE VERY INTERESTED TO LEARN ABOUT ANY UNDOCUMENTED ERRORS THAT MAY OCCUR WHEN RUNNING THIS APPLICATION. Please contact us at spacenvironment@spacenvironment.net if you feel that there is a problem with this application. We realize that users are often under time constraints and are working to deadlines. Therefore, we will do our utmost to fix any significant problems that you bring to our attention and we will notify you of the fix in a timely way. General concerns that are of interest to a broad community of users will be posted in the FAQ section of this document. THANK YOU FOR USING SIP PROFESSIONAL GRADE V2.37 SOLAR IRRADIANCES. S2KPG V2.37 1 Sep 2011