Consolidate the idea of `target_range` in `phase_info` and `Mission.Design.RANGE`

[johnjasa]

Desired capability or behavior.

Currently, if you set the 'target_range' in post_mission within your phase_info object then a constraint will be added to make the mission distance match that value. This is easily confusing with Mission.Design.RANGE also existing. Users might set one or the other thinking it would impact the mission they're evaluating. We should consolidate or clarify this in some way to prevent confusion.

Another consideration is that we're trying to keep the aircraft definition and mission definition as two separate files. If the user sets Mission.Design.RANGE in their .csv, should that directly affect the performed mission length in Aviary? This might need to wait for the notion of off-design to come into Aviary; it's definitely affected.

Please chat with me about more details on this issue before tackling it.

Is your feature request related to a problem? Please describe.

No response

Associated Bug Report

No response

[cmbenne3]

Currently aviary has 3 "Range" variables:

1. Mission.Design.RANGE
   This is the range of the aircraft for the design mission and is used for sizing some subsystem weights (e.g. Avionics.MASS)
2. Mission.Summary.RANGE
   This is the actual range flown on this mission and is calculated inside the Aviary problem.
3. target_range
   This is the range objective for this mission and is set in the phase_info for the analysis.

For a fully converged problem with a range residual (Sizing and Alternate Missions) Mission.Summary.RANGE == target_range, since the range residual constrains this.
For a Sizing mission Mission.Design.RANGE is also equal to summary and target ranges.
A fallout mission has no range residual, target range is not used (and will be defaulted equal to design range). In this case Mission.Summary.RANGE will not be equal to Mission.Design.RANGE unless the gross mass, payload and mission profile are identical to the design mission.

I think the current setup is a little confusing, but I think it is functional.
I could add the above to our documentation for clarity, or alternatively I think we could rename the variables as follows:

1. Mission.Design.RANGE => Aircraft.Design.RANGE
   This parameter is removed from the Mission group and moved to be a property of the aircraft (since it is used for sizing aircraft system weights).
2. Mission.Summary.RANGE => Mission.RANGE - this remains the value that records the actual distance flown by an aircraft for the analyzed mission.
3. target_range => Mission.TARGET_RANGE - moves target range into the variable hierarchy so it is easier to debug/access. This would still be specified in phase_info and it is clearer that this variable specifies the target range the aircraft attempts to fly prior to the optimization. (Mission.RANGE records the actual result).

In order to calculate a range residual for an off design mission for the optimizer I think it is necessary to have the 3 variables, so I don't think we can consolidate them.
Under this setup Aircraft.Design.RANGE removes the confusion about what is actually being flown.
We should add a warning if Mission.TARGET_RANGE and Aircraft.Design.RANGE are not equal for a Sizing mission. We already have code that sets target range to design range if it isn't found in phase info. An optional warning could be added if target_range > design.range.

This also fits with Jason's comment on Issue772:

@ehariton @Kenneth-T-Moore @jkirk5 - what do you all think - should we just document this or is it worth doing some renaming?

[ehariton]

Mission.Design.RANGE => Aircraft.Design.RANGE
I like this change and I think it does help users understand that this is a value used in the aircraft design rather than having anything to do with the actual mission.

Yes i think we should have some warnings if Aircraft.Design.RANGE is smaller than Mission.RANGE or Mission.Target.Rage

We used the Mission.Summary to hold a bunch of other things as well. Are we sure we want to take Range out of there while leaving everything else in?

[cmbenne3]

We used the Mission.Summary to hold a bunch of other things as well. Are we sure we want to take Range out of there while leaving everything else in?

This is a good point - I have listed out the summary and design subclasses of mission to see what variables we have. Interestingly there are unique variables in each and some overlap, I was not expecting that! Lots of these variables under Mission.Design seem like they could either be removed completely, renamed for consistency or moved to Aircraft.Design. Anything else could be moved under Summary, or we remove summary and just go directly under Mission?

Mission.Summary:
These values are inputs and outputs to/from mission analysis for the given mission (whether it is design or off-design).
In on-design these may be constrained to design values, but in off-design they independently represent the final analysis based on the user-selection.

class Summary:	Notes
CRUISE_MACH = 'mission:summary:cruise_mach'	is specified in phase info dictionary, but maybe it's helpful to have as an output the user can query?
CRUISE_MASS_FINAL = 'mission:summary:cruise_mass_final'	very strange quantity to pull out of the trajectory? Do we even need it?
FINAL_MASS = 'mission:summary:final_mass'	is also strange - probably better to use one of TOGW, Operating empty weight, after landing mass, after tax mass? This quantity might be calculates as operating empty weight + reserve fuel - taxi in fuel, which is an odd quantity to describe, or maybe it's after landing before taxi in - either way this name is unclear and should be updated or removed).
FINAL_TIME = 'mission:summary:final_time'	we should rename this to something like Block_time, Mission_Time or Flight_time (depends how it's calculated)
FUEL_BURNED = 'mission:summary:fuel_burned'	this is specific to the mission and should be treated like RANGE
FUEL_FLOW_SCALER = 'mission:summary:fuel_flow_scaler'	Move to Aircraft or Propulsion variables? Not varied per mission?
GROSS_MASS = 'mission:summary:gross_mass'	this is specific to the mission and should be treated like RANGE
RANGE = 'mission:summary:range'	discussed above
RESERVE_FUEL_BURNED = 'mission:summary:reserve_fuel_burned'	Is this the same as Reserve_Fuel if so then should be updated for consistency? it is specific to the mission and should be treated like Range.
TOTAL_FUEL_MASS = 'mission:summary:total_fuel_mass'	this is specific to the mission and should be treated like RANGE

We have another class Mission.Design:

These values MAY change in design mission, but in off-design they cannot change.
In a design mission these are either user inputs or calculated outputs, in off-design they are strictly inputs and do not change.

class Design:	Notes
CRUISE_ALTITUDE = 'mission:design:cruise_altitude'	Specified in Phase Info, mission specific - do we need to record the design value separately from the mission value
CRUISE_RANGE = 'mission:design:cruise_range'	Specified in Phase Info, mission specific - do we need to record the design value separately from the mission value
FUEL_MASS = 'mission:design:fuel_mass'	do we need to record the design value separately from the mission value
FUEL_MASS_REQUIRED = 'mission:design:fuel_mass_required'	Is this the same as FUEL_MASS? Can we just remove?
GROSS_MASS = 'mission:design:gross_mass'	Move to Aircraft.Design.GROSS_MASS?
LIFT_COEFFICIENT = 'mission:design:lift_coefficient'	Move to Aircraft.Design, unless doing a mission analysis with different flap angles then it might need to be mission specific?
LIFT_COEFFICIENT_MAX_FLAPS_UP = 'mission:design:lift_coefficient_max_flaps_up'	Move to Aircraft.Design
MACH = 'mission:design:mach'	If this is a mission only property then remove, otherwise move to Aircraft.Design
RANGE = 'mission:design:range'	Discussed Above
RATE_OF_CLIMB_AT_TOP_OF_CLIMB = 'mission:design:rate_of_climb_at_top_of_climb'	Move to constraints? Or is this a special output that is required?
RESERVE_FUEL = 'mission:design:reserve_fuel'	Is this the same as reserve_fuel_burned? Is so change to consistent name. Do we need to preserve the design value separately from the mission value?
THRUST_TAKEOFF_PER_ENG = 'mission:design:thrust_takeoff_per_eng'	I assume this is for engine scaling, I don't think this is a mission specific property and should be moved to Aircraft or Propulsion hierarchy?