Scene Class

The machupX module is imported through the Python interpreter. All functionality of MachUpX is available through the Scene class. The Scene class takes a file or a Python dictionary containing the configuration information described in ‘Input Files’. Various member functions of Scene can then be called to perform analyses on the aircraft in the scene. Please note that all available functionality for MachUpX is accessed through the Scene class. Accessing lower-level classes and members directly may cause unpredictable and undesired behavior.

class machupX.Scene(scene_input)

A class defining a scene containing one or more aircraft.

Parameters:scene_input (string or dict) – Dictionary or path to the JSON object specifying the scene parameters (see ‘Creating Input Files for MachUp’).
Raises:IOError – If input filepath or filename is invalid
add_aircraft(airplane_name, airplane_input, state={}, control_state={})

Inserts an aircraft into the scene. Note if an aircraft was already specified in the input file, it has already been added to the scene.

Parameters:
  • airplane_name (str) – Name of the airplane to be added.
  • airplane_input (str or dict) – Path to the JSON object or dictionary describing the airplane.
  • state (dict) – Dictionary describing the state of the airplane.
  • control_state (dict) – Dictionary describing the state of the controls.
Raises:

IOError – If the input is invalid.

aircraft_aero_center(aircraft=None, filename=None, verbose=False)

Returns the location of the aerodynamic center of the aircraft at the current state.

Parameters:
  • aircraft (str or list) – The name(s) of the aircraft to determine the aerodynamic center of. Defaults to all aircraft in the scene.
  • filename (str) – Name of a .json file to output the aerodynamic center locations to. Defaults to no file.
  • verbose (bool) – If set to true, information will be output about the progress of Newton’s method. Defaults to False.
Returns:

AC_data – The location of the aerodynamic center in body-fixed coordinates for each aircraft and the moment coefficient about the AC. Structured as:

{
“<AIRCRAFT_NAME>” : {

“aero_center” : [x_ac, y_ac, z_ac], “Cm_ac” : Cm_ac

}

}

Return type:

dict

aircraft_control_derivatives(aircraft=None, dtheta=0.5)

Determines the control derivatives at the current state. Uses a central difference sceme.

Parameters:
  • aircraft (str or list) – The name(s) of the aircraft to determine the aerodynamic derivatives of. Defaults to all aircraft in the scene.
  • dtheta (float) – The finite difference used to perturb the controls in degrees and determine the derivatives. Defaults to 0.5
Returns:

A dictionary of control derivatives with respect to deflection in radians.

Return type:

dict

aircraft_damping_derivatives(aircraft=None, dtheta_dot=0.005)

Determines the damping derivatives at the current state. Uses a central difference sceme. Note, the damping derivatives are non- dimensionalized with respect to 2V/l_ref_lat and 2V/l_ref_lon.

Parameters:
  • aircraft (str or list) – The name(s) of the aircraft to determine the aerodynamic derivatives of. Defaults to all aircraft in the scene.
  • dtheta_dot (float) – The finite difference used to perturb the angular rates of the aircraft and determine the derivatives. Given in radians per second. Defaults to 0.005.
Returns:

A dictionary of damping derivatives.

Return type:

dict

aircraft_derivatives(aircraft=None, filename=None)

Determines the stability, damping, and control derivatives at the current state. Uses a central difference sceme.

Parameters:
  • aircraft (str or list) – The name(s) of the aircraft to determine the aerodynamic derivatives of. Defaults to all aircraft in the scene.
  • filename (str) – File to export the results to. Defaults to no file.
Returns:

A dictionary of stability, damping, and control derivatives.

Return type:

dict

aircraft_mean_aerodynamic_chord(aircraft=None, filename=None, verbose=False)

Returns the mean aerodynamic chord (MAC) for the specified aircraft.

Parameters:
  • aircraft_name (str) – The name of the aircraft to get the reference params for. Does not need to be specified if there is only one aircraft in the scene.
  • filename (str) – JSON file to export the MAC data to. Defaults to None.
Returns:

MAC

MAC data for each aircraft. Structured as

{
“<AIRCRAFT_NAME>” : {

“length” : mean aerodynamic chord length, “C_point” : location of the quarter chord of the MAC determined by Eq. 2.6.2 from Nickel and Wohlfahrt “Tailless Aircraft”

}

}

Return type:

dict

aircraft_pitch_trim(pitch_control='elevator', filename=None, set_trim_state=True, verbose=False)

Returns the required angle of attack and elevator deflection for trim at the current state. THIS SHOULD ONLY BE USED IN THE CASE OF ONE AIRCRAFT IN THE SCENE AND NO WIND.

Parameters:
  • pitch_control (str) – The name of the control that should be used to trim in pitch. Defaults to “elevator”.
  • filename (str) – File to output the results to. Defaults to no file.
  • set_trim_state (bool) – If set to True, once trim is determined, the state of the aircraft will be set to this trim state. If False, the state of the aircraft will return to what it was before this method was called. Defaults to True.
  • verbose (bool) – If set to true, information will be output about the progress of Newton’s method. Defaults to False.
Returns:

The angle of attack and deflection of the specified control required to trim the aircraft in pitch in the current state.

Return type:

dict

aircraft_stability_derivatives(aircraft=None, dtheta=0.5)

Determines the stability derivatives at the current state. Uses a central difference sceme.

Parameters:
  • aircraft (str or list) – The name(s) of the aircraft to determine the aerodynamic derivatives of. Defaults to all aircraft in the scene.
  • dtheta (float) – The finite difference in degrees used to perturb alpha and beta and determine the derivatives. Defaults to 0.5
Returns:

A dictionary of stability derivatives.

Return type:

dict

display_wireframe(show_vortices=True, show_legend=False, filename=None)

Displays a 3D wireframe plot of the scene.

Parameters:
  • show_vortices (bool) – If this is set to True, the distribution of horseshoe vortices along each lifting surface will be shown. Defaults to True.
  • show_legend (bool) – If this is set to True, a legend will appear detailing which color corresponds to which wing segment. Otherwise, the wing segments are all black.
  • filename (str) – File to save an image of the wireframe to. If specified, the wireframe will not be automatically displayed. If not specified, the wireframe will display to the user and not save.
distributions(filename=None, make_plots=[])

Returns various parameters, as well as forces and moments, at each control point for all aircraft at the current state. solve_forces() should be called before this function. Angular distributions are given in radians.

Parameters:
  • filename (str) – Output file to write the distributions to. Saves as a .txt file. Defaults to no file.
  • make_plots (list) – List of keys from the dist dictionary to make plots of. A plot of the parameter as a function of span fraction for each wing segment will then be generated and saved. This can create a lot of plots!
Returns:

dist – A dictionary containing lists of each parameter at each control point. The keys are the aircraft names. The nested keys are then “span_frac”, “cpx”, “cpy”, “cpz”, “chord”, “twist”, “dihedral”, “sweep”, “area”, “alpha”, “Re”, “M”, “section_CL”, “section_Cm”, “section_parasitic_CD”, and “section_aL0”.

Return type:

dict

export_aircraft_stp(aircraft, file_tag='', section_resolution=200, spline=False, maintain_sections=True)

Creates a .stp file representing each lifting surface of the specified aircraft. NOTE: FreeCAD must be installed and configured to use this function.

Parameters:
  • aircraft (str) – The aircraft to export a .stp file of. MAY ONLY SPECIFY ONE.
  • file_tag (str, optional) – Optional tag to prepend to output filename default. The output files will be named “<AIRCRAFT_NAME>_<WING_NAME>.stp”.
  • section_resolution (int, optional) – Number of points to use in discretizing the airfoil section outline. Defaults to 200.
  • spline (bool, optional) – Whether the wing segment sections should be represented using splines. This can cause issues with some geometries/CAD packages. Defaults to False.
  • maintain_sections (bool, optional) – Whether the wing segment sections should be preserved in the loft. Defaults to True.
export_stl(filename, section_resolution=200, aircraft=None)

Generates a 3D model of the aircraft. If only one aircraft is specified, the model is centered on that aircraft’s origin. If more than one aircraft is specified, the model is centered on the origin of the earth- fixed coordinate system.

Parameters:
  • filename (str) – Name of the file to export the model to. Must be .stl.
  • section_resolution (int) – Number of points to use in dicretizing the airfoil section outlines. Defaults to 200.
  • aircraft (str or list) – Name(s) of the aircraft to include in the model. Defaults to all aircraft in the scene.
get_aircraft_reference_geometry(aircraft=None)

Returns the reference geometries for the specified aircraft.

Parameters:aircraft_name (str) – The name of the aircraft to get the reference params for. Does not need to be specified if there is only one aircraft in the scene.
Returns:
  • S_w (float) – Reference area
  • l_ref_lon (float) – Longitudinal reference length
  • l_ref_lat (float) – Lateral reference length
set_aircraft_control_state(control_state={}, aircraft_name=None)

Sets the control state of the given aircraft.

Parameters:
  • control_state (dict) – Dictionary describing the control state. Each key value pair should be the name of the control and its deflection in degrees.
  • aircraft_name (str) – The name of the aircraft to set the state of. If there is only one aircraft in the scene, this does not need to be specified.
set_aircraft_state(state={}, aircraft_name=None)

Sets the state of the given aircraft.

Parameters:
  • state (dict) – Dictionary describing the state as specified in ‘Creating Input Files for MachUp’. The state type may be aerodynamic or rigid-body, regardless of how the state was originally specified. Any values not given default to their original defaults. The previous state of the aircraft is in no way preserved.
  • aircraft_name (str) – The name of the aircraft to set the state of. If there is only one aircraft in the scene, this does not need to be specified.
solve_forces(filename=None, non_dimensional=True, dimensional=True, verbose=False)

Solves the NLL equations to determine the forces and moments on the aircraft.

Parameters:
  • filename (str) – File to export the force and moment results to. Should be .json. If not specified, results will not be exported to a file.
  • non_dimensional (bool) – If this is set to True, nondimensional coefficients will be included in the results. Defaults to True.
  • dimensional (bool) – If this is set to True, dimensional forces and moments will be included in the results. Defaults to True.
  • verbose (bool) – Display the time it took to complete each portion of the calculation. Defaults to False.
Returns:

Dictionary of forces and moments acting on each wing segment.

Return type:

dict