ReportFile

 

 

Lead: Rizwan Qureshi

Developer: Linda O. Jun

Tester: John M. Bez

 

 

Explore

Known Bugs

Failing Tests

Other Findings

Requirements

Interface/Functional Spec

Overview

Description

Fields

GUI

Remarks

Examples

Test Procedures

Assumptions

Nominal Tests

ReportFile Settings Tests

Edge/Corner/Miscellaneous Tests

Unique Validation Tests

 

 

 

 

 

 

Explore

 

Known Bugs

 

JIRA Bugs:

 

I did a bug search in JIRA by selecting ReportFiles (FRR-30) under components and found following P1 or P2 issues for FRR-30 ReportFile feature:

 

      GMT-2734 FRR-30 ReportFile Code QA

 

 

Failing Tests

 

 

ReportFile_SoverIterations_All_DC    on 05/12 nightly test: Passing     

ReportFile_SoverIterations_None_DC  on 05/12 nightly test:  Passing

 

ReportFile_SolverIterations_All_VF13ad1_optimzer  on 05/12 nightly test: Passing

ReportFile_SolverIterations_None_VF13ad1_optimzer on 05/12 nightly test: Passing

 

Other Findings

 

 

Issue 3: If the user adds any hardware with the spacecraft such as fuel tanks, then the user can only ask for fuel mass left in the attached tank(s) through script and not via the GUI. In ReportFile window and in the ‘ParameterSelectDialoge’ window, no GUI icon for hardware shows up and there is no way to add fuel mass left in the attached tank(s) via GUI.

 

Recommendation:  Fix (Fix by: R2013a, Priority: Should it be P1, P2? 

As per Linda’s input, I created a bug: GMT-2681 Priority is: P1 Linda fixed it. VERIFIED and CLOSED

 

 

Issue4A: This issue pertains to when the user tries to use the field called SolverIterations when involving iterative process such as differential correction. The option of selecting 'All' for field name SolverIterations under ReportFile Resource should show the user all iterations and perturbations until Achieve command is satisfied within the Targeter. Rather when the script is ran, only the first value of the iteration is reported to the reportfile.

 

Recommendation: I plan to report this as a bug in JIRA and will attach script and truth file there. Fix (Fix by: R2013a,  Priority: Should it be P1, P2 or even P3)?

As per Linda’s input, I created a bug: GMT-2752                 Linda fixed it. VERIFIED and Closed              

 

 

Issue 4B: This issue pertains to when the user tries to use the field called SolverIterations when involving iterative process such as differential correction. The option of selecting 'None' for field name SolverIterations under ReportFile Resource should show the user final solution only that the user is attempting to achieve under the Achieve command. Rather when the script is ran, first the reportfile being reported under Output tree is empty and also no reportfile gets reported to default Output folder which is located in directory where GMAT software is installed.

 

Recommendation: I plan to report this as a bug in JIRA and will attach script and truth file there. Fix (Fix by: R2013a,  Priority: Should it be P1, P2 or even P3)?

As per Linda’s input, I created a bug: GMT-2752               Linda fixed it. VERIFIED and Closed

 

Issue5A: This issue pertains to when the user tries to use the field called SolverIterations when involving iterative process such as VF13ad1 optimizer. The option of selecting 'All' for field name SolverIterations under ReportFile Resource should show the user all iterations and perturbations until NonlinearConstraint and Minimize commands are satisfied within the VF13ad1 optimizer. Rather when the script is ran, only the first values of the iteration are reported to the reportfile.

 

Recommendation: I plan to report this as a bug in JIRA and will attach script and truth file there. Fix (Fix by: R2013a,  Priority: Should it be P1, P2 or even P3)?

As per Linda’s input, I created a bug: GMT-2752               Linda fixed it.   VERIFIED and Closed

 

 

Issue5B: This issue pertains to when the user tries to use the field called SolverIterations when involving iterative process such as VF13ad1 optimizer. The option of selecting 'None' for field name SolverIterations under ReportFile Resource should show the user only the final solution in their reportfile. Rather when the script is ran, first the reportfile being reported under Output tree is empty and also no reportfile gets reported to default Output folder which is located in directory where GMAT software is installed.

 

Recommendation: I plan to report this as a bug in JIRA and will attach script and truth file there. Fix (Fix by: R2013a,  Priority: Should it be P1, P2 or even P3)?

As per Linda’s input, I created a bug: GMT-2752               Linda fixed it.  VERIFIED and Closed

 

 

Requirements

These are here for review purposes only and will be migrated to formal SRS when complete.

 

To CCB lead (SPH): These are the final requirements and need to be migrated to formal SRS.

These were finalized by CCB as of 17 July 2012 and are here for reference purposes only.  See the SRS for requirements. -SPH

 

FRR-30.1

The system shall support ASCII report files.

 

FRR-30.2.0

The system shall allow the user to define reported data using any of the following:

FRR-30.2.1

1)                Calculation parameter as defined in FRR-32

FRR-30.2.2

2)                User defined variable

FRR-30.2.3

3)                User defined array

FRR-30.2.4

4)                User defined string

FRR-30.2.5

5)         Fuel-tank properties

FRR-30.2.6

6)         Thruster properties

FRR-30.2.7

7)                User defined array element

FRR-30.3.0

The system shall allow the user to set the following properties:

FRR-30.3.1

1)                Data column width

FRR-30.3.2

2)                Data precision

FRR-30.3.3

3)                Zero Fill

FRR-30.4.0

The system shall allow the user to specify the following column formats:

FRR-30.4.1

1)                Right-justified

FRR-30.4.2

2)                Left-Justified

FRR-30.5

The system shall allow the user to optionally display header information describing the data in each column.

FRR-30.6.0

The system shall allow the user to specify how data is written to reports during iterative processes such as differential correction and optimization. The following options shall be available:

FRR-30.6.1

1)                  Write all iterations/perturbations to file

FRR-30.6.2

2)          Write only the solution to the file (No iterations or perturbations)

FRR-30.6.3

3)          Write current iteration/perturbation

FRR-30.7

The system shall allow the user to optionally write or not write data to an existing report file.

FRR-30.8.0

The system shall allow the user to define the report file location using the following options:

FRR-30.8.1

1)  Relative file path   

FRR-30.8.2

2)  Absolute file path   

FRR-30.9

The system shall allow the user to define the name of the report file.

 

 

Interface/Functional Spec

Overview

 

The ReportFile is a user-defined file where values of selected objects can be viewed in a report format.

Description

 

The ReportFile allows you to write data to a text file that can be viewed after a mission run has been completed. GMAT allows you to report user-defined arrays, array elements, user-defined strings or variables and parameters. GMAT gives you control over setting formatting properties of the report file that is generated at the end of a mission run. GMAT allows you to create ReportFiles in either the GUI or script interface. GMAT also provides the option of when to write and stop writing data to a text file through the Toggle On/Off command. See the Remarks section below for detailed discussion of the interaction between ReportFile object and Toggle command.  

 

See Also :  Report command, Toggle command

 

 

 

Fields

 

See the User Interface Spec spreadsheet for reference information for fields.

 

GUI

 

Figure below shows default settings for ReportFile resource:

 

                  Figure: Default Name and Settings for the ReportFile Object Dialog Box

 

 

 

 

 

Remarks

 

 

Behavior When using Filename field

 

GMAT allows you to specify the name of the report file in two ways: The default naming convention for a report file when using FileName field is shown below:

Create ReportFile aReport;

GMAT aReport.Filename = 'ReportFile1.txt';

GMAT aReport.WriteReport = true;

 

An alternate method for naming a report file is to name the file without using any single quotes around the report file’s name.

Create ReportFile aReport;

GMAT aReport.Filename = ReportFile1.txt;

GMAT aReport.WriteReport = true;

 

 

How data is reported to a report file

 

GMAT allows you to report data to a report file in two ways: You can use ReportFile.Add field or a Report command.

 

You can add data using the .Add field of ReportFile resource and this method reports data to the report file at each propagation step. Below is an example script snippet that shows how to report epoch and selected orbital elements using the ReportFile.Add field:

 

Create Spacecraft aSat;

Create ReportFile aReport;

 

GMAT aReport.Add = {aSat.UTCGregorian aSat.Earth.SMA, aSat.Earth.ECC, aSat.Earth.TA, aSat.EarthMJ2000Eq.RAAN};

 

Create Propagator aProp;

 

BeginMissionSequence;

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0};

 

 

Caution: GMAT’s ReportFile.Add field will not report selected data to the report file at each propagation step if Propagate command is not included under the BeginMissionSequence.

 

 

An alternative method of reporting data to the report file is via the Report command. Using the Report command allows you to report data to the report file at specific points in your mission.

Below is an example script snippet that shows how to report epoch and selected orbital elements using the Report command:

 

Create Spacecraft aSat;

Create ReportFile aReport;

 

Create Propagator aProp;

 

BeginMissionSequence;

 

Report aReport aSat.UTCGregorian aSat.Earth.SMA aSat.Earth.ECC aSat.Earth.TA aSat.EarthMJ2000Eq.RAAN

 

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0};

 

Report aReport aSat.UTCGregorian aSat.Earth.SMA aSat.Earth.ECC aSat.Earth.TA aSat.EarthMJ2000Eq.RAAN

 

 

 

 

Behavior and Interactions when using ReportFile Resource & Report Command

 

Suppose you utilize a ReportFile resource and opt not to write a report and select false for the field name WriteReport, as shown in the example below:

 

Create ReportFile aReport;

GMAT aReport.Filename = ReportFile1.txt;

GMAT aReport.Add = {aSat.A1ModJulian, aSat.Earth.SMA};

GMAT aReport.WriteReport = false;

 

Now assume that at the same time, you decide to utilize Report Command, as shown in the example script snippet below :

 

BeginMissionSequence;

Report aReport aSat.A1ModJulian aSat.Earth.SMA aSat.Earth.ECC;

Propagate aProp(aSat) {aSat.Earth.Periapsis};

Report aReport aSat.A1ModJulian aSat.Earth.SMA aSat.Earth.ECC;

 

At this point, you may think that since false option is selected under the field name WriteReport in ReportFile resource, hence GMAT will not generate the report file called ReportFile1.txt. On the Contrary, GMAT will generate a report called ReportFile1.txt but that report will only contain data that was requested using the Report Command. ReportFile1.txt text file will contain epoch, semi-major-axis and eccentricity only at specific points of the mission.

 

 

Behavior when reporting data in Iterative Processes

 

GMAT allows you to specify how data is written to reports during iterative processes such as differential correction or optimization. SolverIterations field of ReportFile resource supports 3 options which are described in the table below:

 

 

SolverIterations options

Description

Current

Shows only current iteration/perturbation after the end of an iterative process and reports current solution to a report file.

All

Shows all iterations/perturbations in an iterative process and reports all iterations/perturbations to a report file.

None

Shows only final solution after the end of an iterative process and reports only final solution to a report file.

 

 

Where Reports Are written

 

GMAT allows you to write reports to any desired path or location. You can do this by going to GMAT’s startup file called  gmat_startup_file.txt and define a path under OUTP UT_PATH .

 

If no path is provided and only name of the report file is defined in the FileName field of ReportFile resource, then report files are written to the default path defined in gmat_startup_file.txt. The default path where reports are written to is the output folder located in the main directory where GMAT is installed.

 

Below is an example script snippet that shows where generated reports are written to when only report file’s name is provided under the FIleName field. In this example, ‘ReportFile1.txt’ report is written to the output folder located in the main directory where GMAT is installed:

 

Create ReportFile aReport;

 

GMAT aReport.Filename = 'ReportFile1.txt';

GMAT aReport.Add = {aSat.A1ModJulian, aSat.Earth.ECC};

 

 

 

An alternate method where report files can be written is by defining a relative path. You can define the relative path in GMAT’s startup file gmat_startup_file.txt under OUTPUT_PATH . For example, you can set a relative path by setting                  

OUTPUT_PATH = C:/Users/rqureshi/Desktop/GMAT/mytestfolder/../output2/ .

In the above path, the syntax ".." means to “go up one level”. When the script is executed, the generated report file named under FileName field will be written to a path C:\Users\rqureshi\Desktop\GMAT\output2

 

Another method where report files can be written to is by defining an absolute path in GMAT’s startup file gmat_startup_file.txt under OUTPUT_PATH. For example, you can set an absolute path by setting

OUTPUT_PATH = C:/Users/rqureshi/Desktop/GMAT/mytestfolder/

When the script is executed, report file named under FileName field will be written to an absolute path C:\Users\rqureshi\Desktop\GMAT\mytestfolder

 

 

Behavior when using ReportFile Resource & Toggle Command

 

GMAT allows you to use Toggle command while using the Add field of ReportFile resource. When Toggle Off command is issued for a ReportFile, not data is sent to a report file until a Toggle On command is issued. Similarly when a Toggle On command is used, data is sent to a report file at each integration step until a Toggle Off command is used.  

 

Below is an example script snippet that shows how to use Toggle Off and Toggle On command while using the ReportFile resource. Spacecraft’s cartesian position vector is reported to the report file.

 

Create Spacecraft aSat;

Create Propagator aProp;

 

Create ReportFile aReport;

GMAT aReport.Filename = 'ReportFile1.txt';

aReport.Add = {aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y aSat.EarthMJ2000Eq.Z};

 

BeginMissionSequence;

 

Toggle aReport Off;

Propagate aProp(aSat) {aSat.ElapsedDays = 2};

Toggle aReport On;

Propagate aProp(aSat) {aSat.ElapsedDays = 4};

 

 

 

 

Examples

Propagate an orbit and write cartesian state to a report file at every integrator step

 

Create Spacecraft aSat;

Create Propagator aProp;

 

Create ReportFile aReport;

GMAT aReport.Filename = 'ReportFile1.txt';

aReport.Add = {aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y aSat.EarthMJ2000Eq.Z aSat.EarthMJ2000Eq.VX aSat.EarthMJ2000Eq.VY aSat.EarthMJ2000Eq.VZ};

 

BeginMissionSequence;

 

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0};

 

Propagate an orbit for 1 day and write cartesian state to a report file at specific points in your mission

 

Create Spacecraft aSat;

Create Propagator aProp;

 

Create ReportFile aReport;

GMAT aReport.Filename = 'ReportFile1.txt';

 

BeginMissionSequence;

 

Report aReport aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y aSat.EarthMJ2000Eq.Z aSat.EarthMJ2000Eq.VX aSat.EarthMJ2000Eq.VY aSat.EarthMJ2000Eq.VZ

 

Propagate aProp(aSat) {aSat.ElapsedDays = 1};

 

Report aReport aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y aSat.EarthMJ2000Eq.Z aSat.EarthMJ2000Eq.VX aSat.EarthMJ2000Eq.VY aSat.EarthMJ2000Eq.VZ

 

 

 

 

Test Procedures

 

Assumptions

 

      All tests use both default and non-default values

 

 

 

File Naming Conventions

 

The goal of the naming convention is to allow people to intuitively understand the purpose of the test by the name of the test file. The file naming conventions in this section are guidelines to be used when they “make sense” and are to be modified when they don’t “make sense”. They’re not strict rules.

 

ReportFile uses the following format for nominal tests:

 

ReportFile_ <description of test>

Use the following format for validation tests:

ReportFile_Validation_<Field>_ <description of test>

Nominal Tests

 

Priority

Status

Summary

P1

Done

SPH

Test whether the system allows defining of reported-variables using calculation parameters as defined in FRR-32

P1

Done

SPH

Test whether the system allows defining of reported-variables using user-defined variables

P1

Done

SPH

Test whether the system allows defining of reported-variables using user-defined array or array elements

P1

Done

SPH

Test whether the system allows defining of reported-variables using user-defined string

      P1

Done

RHQ

Test whether the system allows the user to specify how data is written to report file during iterative process such as Differential Correction. Testing includes employing all available options for SolverIterations.

     P1

Done

RHQ

test whether the system allows the user to specify how data is written to report file during iterative process such as optimization.

Testing includes employing all available options for SolverIterations.

PI

Done

RHQ

Test reporting attached hardware (fuel tank and thruster) properties during a finite and impulsive burn

 

ReportFile Settings Tests

The objective of these tests is to test ReportFile settings such as ColumnWidth, Precision, ZeroFill for example.

 

Priority

Status

Summary

P1

Done

SPH

Test ColumnWidth by setting it to default and then multiple non-default values.

P1

Done

SPH

Test Precision by setting it to default and then multiple non-default values.

P1

Done

SPH

Test ZeroFill by setting it to default and then multiple non-default values.

P1

Done

SPH

Test LeftJustify and RightJustify by turning LeftJustify On and then Off

P1

Done

SPH

Test multiple field settings and their interactions with each other: When Precision < ColumnWidth < Precision

P1

Done

SPH

Test multiple field settings and their interactions with each other: WriteHeaders field and ColumnWidth

P1

Done

SPH

Test multiple variables being reported to Add field and seeing if they appear in reportfile

P1

Done

SPH

Test calculation parameter defined in FRR-32 in a Differential Corrector

P1

Done

SPH

Test calculation parameter defined in FRR-32 in an Optimizer

 

Edge/Corner/Miscellaneous Tests

 

I cannot think of any as of yet.

 

Priority

Status

Summary

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Unique Validation Tests

These are unique validation tests that are required for special field or object couplings for this ReportFile feature.

 

Priority

Status

Summary

P1

SPH

Done

Test range constraints on Add field

P1

SPH

Done

 

Test range constraints on ColumnWidth field

P1

SPH

Done

Test range constraints on LeftJustify field

P1

SPH

Done

Test range constraints on Precision field

P1

SPH

Done

Test range constraints on SolverIterations field

P1

SPH

Done

 

Test range constraints on WriteHeaders field

P1

SPH

Done

Test range constraints on WriteReport field

P1

SPH

Done

Test range constraints on ZeroFill field

 

 

 

Unique Mode Tests

 

I cannot think of any unique mode tests for this object.

 

Priority

Status

Summary

 

 

 

 

 

 

 

 

 

 

 

Unique GUI Tests

 

These are tests that are unique to the GUI interface for this feature that are not covered by the standard GUI test template and procedures.

 

 

Priority

Status

Summary