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, optional) – Dictionary or path to the JSON object specifying the scene parameters (see ‘Creating Input Files for MachUp’). If not specified, all default values are chosen.
Raises:	`IOError` – If input filepath or filename is invalid

MAC(**kwargs)¶

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

Parameters:

aircraft (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

add_aircraft(airplane_name, airplane_input, state={}, control_state={})¶

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

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

aero_center(**kwargs)¶

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

control_derivatives(**kwargs)¶

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

Parameters:	aircraft (str or list) – The name(s) of the aircraft to determine the control 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 body_frame (boolean, optional) – Whether to output results in the body-fixed frame. Defaults to True. stab_frame (boolean, optional) – Whether to output results in the stability frame. Defaults to False. wind_frame (boolean, optional) – Whether to output results in the wind frame. Defaults to True.
Returns:	A dictionary of control derivatives with respect to deflection in radians.
Return type:	dict

damping_derivatives(**kwargs)¶

Determines the damping derivatives at the current state. Uses a central difference scheme. Note, the damping derivatives are non- dimensionalized with respect to 2V/l_ref_lat and 2V/l_ref_lon. Also, the angular rates for the damping derivatives will be in the frame the angular rates were originally given in.

Parameters:	aircraft (str or list) – The name(s) of the aircraft to determine the damping 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. body_frame (boolean, optional) – Whether to output results in the body-fixed frame. Defaults to True. stab_frame (boolean, optional) – Whether to output results in the stability frame. Defaults to False. wind_frame (boolean, optional) – Whether to output results in the wind frame. Defaults to True.
Returns:	A dictionary of damping derivatives.
Return type:	dict

derivatives(**kwargs)¶

Determines the stability, damping, and control derivatives at the current state. Uses a central difference scheme. Note that the angular rates for the damping derivatives will be in the frame the angular rates were originally given in.

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. body_frame (boolean, optional) – Whether to output results in the body-fixed frame. Defaults to True. stab_frame (boolean, optional) – Whether to output results in the stability frame. Defaults to False. wind_frame (boolean, optional) – Whether to output results in the wind frame. Defaults to True.
Returns:	A dictionary of stability, damping, and control derivatives.
Return type:	dict

display_planform(**kwargs)¶

Displays an overhead plot of the specified aircraft. Note the plot will not reflect the current set orientation of the aircraft nor its current position in Earth-fixed coordinates.

Parameters:

aircraft (str or list) – The name(s) of the aircraft to plot the planform of. Defaults to all aircraft in the scene.
file_tag (str, optional) – File tag to be used in saving the plot(s). The plot(s) will be saved to “<AIRCRAFT_NAME>_planform_file_tag.png”. If specified, the planform(s) will not be automatically displayed. If not specified, the planform(s) will display to the user and not save.

display_wireframe(**kwargs)¶

Displays a 3D wireframe plot of the scene.

Parameters:

show_vortices (bool, optional) – If this is set to True, the distribution of horseshoe vortices along each lifting surface will be shown. Defaults to True.
show_legend (bool, optional) – 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. Defaults to False.
filename (str, optional) – 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(**kwargs)¶

Returns various parameters, as well as forces and moments, at each control point for all aircraft at the current state. Note that if “correct_sections_for_sweep” (default True) is set to True, the section aerodynamic properties given here will be the swept section properties. All angular values are given in radians by default.

The following properties are stored as distributions:

“span_frac” : fraction along the span (distance along the LQC projected into the y-z plane)

“cpx” : control point x location

“cpy” : control point y location

“cpz” : control point z location

“chord” : section geometric chord

“swept_chord” : section chord normal to the lifting-line (corrected for sweep)

“twist” : section geometric twist

“dihedral” : section geometric dihedral

“sweep” : section geometric sweep

“aero_sweep” : section aerodynamic sweep (based on the lifting-line)

“area” : section differential planform area

“alpha” : angle of attack (corrected for sweep)

“delta_flap” : flap deflection

“u” : body-x velocity

“v” : body-y velocity

“w” : body-z velocity

“Re” : Reynolds number

“M” : Mach number

“q” : dynamic pressure

“section_CL” : lift coefficient

“section_Cm” : moment coefficient

“section_parasitic_CD” : drag coefficient

“section_aL0” : zero-lift angle of attack

“Fx” : body-x force acting on each section

“Fy” : body-y force acting on each section

“Fz” : body-z force acting on each section

“Mx” : body-x moment acting on each section

“My” : body-y moment acting on each section

“Mz” : body-z moment acting on each section

“circ” : circulation

“CD_i” : induced drag coefficient acting on each section (nondimensionalized by the freestream velocity and the section discrete area dS)

Parameters:	filename (str) – Output file to write the distributions to. Saves as a .txt file. Defaults to no file. radians (bool) – Whether to output angular values in radians. Defaults to True. If set to False, all angular values will be output in degrees. Note this also affects the plots generated by make_plots. make_plots (list, optional) – 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! show_plots (bool, optional) – Whether to show the plots, rather than automatically saving them. Defaults to False.
Returns:	dist – A dictionary containing lists of each parameter at each control point. The distributions are organized by aircraft then by wing segment. The nested keys are then each parameter.
Return type:	dict

export_dxf(**kwargs)¶

Creates a .dxf file representing each lifting surface of the specified aircraft.

Parameters:

aircraft (str, optional) – The aircraft to export .dxf files of.
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.
number_guide_curves (int, optional) – Number of guidecurves to create. Defaults to 2 (one at the leading edge, one at the trailing edge).
export_english_units (bool, optional) – Whether to export the dxf file in English units. Defaults to True.
dxf_line_type (str, optional) – Type of line to be used in the .dxf file creation. Options include ‘line’, ‘spline’, and ‘polyline’. Defaults to ‘spline’.
export_as_prismoid (bool, optional) – Whether to export each airfoil as a rectangle. Forces number_guide_curves to 4 and section_resolution to 5. Defaults to False.

export_pylot_model(**kwargs)¶

Creates a JSON object containing a linearized model of the aircraft to use as input for Pylot (www.github.com/usuaero/Pylot). Any information not available to MachupX but required for Pylot will be filled with “PLEASE SPECIFY” and must be changed by the user before the input can be used for Pylot. Note, this can only be used if there is one aircraft in the scene.

We designed the input files for Pylot to be cross-compatible with MachUpX. With this in mind, if values are already specified in the input but those values are not used in MachUpX, they will still be included in the input file exported here.

Note, this will set the aircraft state to zero aerodynamic angles and zero control deflections.

Parameters:

filename (str, optional) – Name of the JSON file to write the model to. Must be “.json”. Defaults to “<AIRCRAFT_NAME>_linearized.json”.
inertia (dict, optional) –
Moments of inertia for the aircraft, formatted as

{

“Ixx” : <VALUE>, “Iyy” : <VALUE>, “Izz” : <VALUE>, “Ixy” : <VALUE>, “Ixz” : <VALUE>, “Iyz” : <VALUE>

}

If not specified, this will be left blank for the user to specify after the fact. Alternatively, if “inertia” was already part of the aircraft input, it will remain the same as inputted.
angular_momentum (list, optional) – Angular momentum vector. Defaults to [0.0, 0.0, 0.0]. Alternatively, if “angular_momentum” was already part of the aircraft input, it will remain the same as inputted.
stall_angle_of_attack (float, optional) – Angle of attack in degrees at which the aircraft stalls.
stall_sideslip_angle (float, optional) – Sideslip angle in degrees at which the aircraft stalls laterally.
controller_type (str, optional) – The controller that will be used with the exported model. Can be “keyboard”, “joystick”, “user_defined”, or “time_sequence”. This affects whether certain inputs unknown to MachUpX are marked “PLEASE SPECIFY”. If not given, all such keys will be marked “PLEASE SPECIFY”.
velocity (float, optional) – Velocity at which to evaluate the model. Should not have any effect unless Mach and Reynolds number effects are included. Defaults to 100.
set_accel_derivs (bool, optional) – Whether to set derivatives with respect to vertical and lateral acceleration to zero. Defaults to False, in which case the user must specify these.

export_stl(**kwargs)¶

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, optional) – Number of points to use in dicretizing the airfoil section outlines. Defaults to 200. Note this is the number of outline points where two exist at the trailing edge. Thus the number of panels will be one less than this number.
aircraft (str or list, optional) – Name(s) of the aircraft to include in the model. Defaults to all aircraft in the scene.
close_te (bool, optional) – Whether to force the trailing edge to be sealed. Defaults to true

export_stp(**kwargs)¶

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, optional) – The aircraft to export a .stp file of. Defaults to all aircraft in the scene.
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.
close_te (bool, optional) – Whether to force the trailing edge to be sealed. Defaults to true

export_vtk(**kwargs)¶

Generates a 3D model of the specified aircraft in body-fixed coordinates using the VTK format. This will generate an unstructured mesh of 4-sided polygons, (except where triangles are required to resolve the mesh).

Parameters:

filename (str) – Name of the file to export the model to. Must be .vtk.
section_resolution (int, optional) – Number of points to use in dicretizing the airfoil section outlines. Defaults to 200. Note this is the number of outline points where two exist at the trailing edge. Thus the number of panels will be one less than this number.
aircraft (str, optional) – Name of the aircraft. If there is only one aircraft in the scene, this is optional.
close_te (bool, optional) – Whether to force the trailing edge to be sealed. Defaults to True

get_aircraft_reference_geometry(aircraft=None)¶

Returns the reference geometries for the specified aircraft.

Parameters:	aircraft (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. Only one may be specified.
Returns:	S_w (float) – Reference area l_ref_lon (float) – Longitudinal reference length l_ref_lat (float) – Lateral reference length

get_max_bound_vortex_length()¶: Returns the maximum bound vortex segment length in the scene.

out_gamma()¶

Plots the induced velocities and writes the circulation distribution to a file.

Author: Francois Fortin

pitch_trim(**kwargs)¶

Returns the required angle of attack and pitch control deflection for trim at the current state. Trim is achieved when the lift cancels out the weight of the aircraft and the pitching moment is zero. This alters the body-fixed aircraft velocity in order to achieve trim.

It is recommended this trim function be used when the aircraft is the only one in the scene, there is no wind, and the bank angle is zero (a majority of cases). For more complex cases, pitch_trim_using_orientation() is recommended.

Parameters:	aircraft (str, optional) – Aircraft to trim in pitch. If there is only one aircraft in the scene, this does not need to be given. CL (float, optional) – Lift coefficient to trim the aircraft to. Defaults to the aircraft’s weight coefficient. Cm (float, optional) – Pitching moment coefficient to trim the aircraft to. Defaults to 0.0. 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. Note this will only affect the velocity of the aircraft; its orientation will remain unchanged. If False, the state of the aircraft will return to what it was before this method was called. Defaults to True. max_iterations (int) – Maximum number of iterations to use in the iterative solver. Defaults to 100. relaxation (float) – Relaxation factor to use in the iterative solver. Defaults to 1.0. 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

pitch_trim_using_orientation(**kwargs)¶

Trims the given aircraft in pitch by altering the elevation angle of the aircraft and the specified control deflection. This will maintain the Earth-fixed velocity of the aircraft and the heading and bank angle. Since bank angle is maintained, trim is achieved when the vertical component of lift cancels out the weight of the aircraft.

This trim function is more general than pitch_trim() and can be used in all cases.

Parameters:

aircraft (str, optional) – Aircraft to trim in pitch. If there is only one aircraft in the scene, this does not need to be given.
CL (float, optional) – Lift coefficient to trim the aircraft to. Defaults to the aircraft’s weight coefficient.
Cm (float, optional) – Pitching moment coefficient to trim the aircraft to. Defaults to 0.0.
pitch_control (str, optional) – Control to be used to trim the aircraft in pitch. Defaults to “elevator”.
set_trim_state (bool, optional) – Whether to use the determined trim state as the new state of the aircraft. This will maintain the Earth-fixed velocity of the aircraft while changing the elevation angle. Defaults to True.
max_iterations (int) – Maximum number of iterations to use in the iterative solver. Defaults to 100.
relaxation (float) – Relaxation factor to use in the iterative solver. Defaults to 1.0.
filename (str) – File to output the results to. Defaults to no file.
verbose (bool, optional) –

Returns:

trim_state (dict) – The aircraft state at trim.
trim_controls (dict) – The control deflections at trim.

remove_aircraft(airplane_name)¶

Removes an aircraft from the scene.

Parameters:	airplane_name (str) – Name of the airplane to be removed.

set_aircraft_control_state(control_state={}, aircraft=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 (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=None)¶

Sets the state of the given aircraft.

Parameters:	state (dict) – Dictionary describing the state as specified in ‘Creating Input Files for MachUp’. Any values not given default to their original defaults. The previous state of the aircraft is in no way preserved. aircraft (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_err_state(**kwargs)¶

Sets how errors are to be handled.

Each error type can be set to “raise”, “warn”, or “ignore”. If set to “raise”, the error will be raised and execution will be interrupted. If set to “warn”, a warning will be given, but execution will be allowed to continue. If set to “ignore”, no message will be given and execution will continue. This can only be set for custom exceptions defined for MachUpX and AirfoilDatabase.

All will default to “raise” if not specified.

Parameters:	not_converged (str, optional) – How to handle the SolverNotConvergedError. database_bounds (str, optional) – How to handle the DatabaseBoundsError. poly_fit_bounds (str, optional) – How to handle PolyFitBoundsError.

solve_forces(**kwargs)¶

Solves the NLL equations to determine the forces and moments on each 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. report_by_segment (bool) – Whether to include results broken down by wing segment. Defaults to False. body_frame (boolean, optional) – Whether to output results in the body-fixed frame. Defaults to True. stab_frame (boolean, optional) – Whether to output results in the stability frame. Defaults to False. wind_frame (boolean, optional) – Whether to output results in the wind frame. Defaults to True. initial_guess (str, optional) – Sets the initial guess for the nonlinear solver. May be ‘linear’ or ‘previous’. If ‘linear’, the linear solver is first run to determine an estimate for the vortex strength distribution. If ‘previous’, the last determined vortex strength distribution is used as an initial guess; this will be from the last time `Scene.solve_forces()` was called or will be zero if `Scene.solve_forces()` has not previously been called (note that `Scene.solve_forces()` is called by other functions, such as `derivatives()` etc.). Defaults to ‘linear’. Only affects execution if the nonlinear solver is used. This has no effect on the final solution, only convergence rates. It should also be noted that in most instances using ‘previous’ will actually increase the number of iterations required for convergence. This should be used with prudence. verbose (bool) –
Returns:	FM – Dictionary of forces and moments acting on each wing segment.
Return type:	dict

stability_derivatives(**kwargs)¶

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

Parameters:	aircraft (str or list) – The name(s) of the aircraft to determine the stability 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 body_frame (boolean, optional) – Whether to output results in the body-fixed frame. Defaults to True. stab_frame (boolean, optional) – Whether to output results in the stability frame. Defaults to False. wind_frame (boolean, optional) – Whether to output results in the wind frame. Defaults to True.
Returns:	A dictionary of stability derivatives.
Return type:	dict

state_derivatives(**kwargs)¶

Determines the derivatives of forces and moments at the current state with respect to the 13 element state vector. Uses a central difference scheme. These states are:

Position in Earth-fixed coordinates. Velocity in body-fixed coordinates. Orientation of the body frame relative to the Earth-fixed frame. Angular rate in body-fixed coordinates.

These derivatives will always be determined using the body-fixed forces and moments.

Parameters:	aircraft (str or list) – The name(s) of the aircraft to determine the stability derivatives of. Defaults to all aircraft in the scene. dx (float) – The finite difference used to perturb position in either feet or meters. Defaults to 0.5. dV (float) – The finite difference used to perturb velocity in either ft/s or m/s. Defaults to 0.5. de (float) – The finite difference used to perturb the orientation quaternion. Defaults to 0.001. dw (float) – The finite difference used to perturb the angular rates in rad/s. Defaults to 0.01.
Returns:	A dictionary of state derivatives.
Return type:	dict

target_CL(**kwargs)¶

Determines the angle of attack necessary to produce the specified lift coefficient with the specified control deflections. MAY ONLY BE USED IF THERE IS ONE AIRCRAFT IN THE SCENE AND THE WIND IS CONSTANT.

Parameters:	CL (float) – Target lift coefficient. control_state (dict, optional) – Control deflections. Defaults to no deflections. set_state (bool, optional) – Whether to set the state of the aircraft to the angle of attack determined. filename (str, optional) – File to output results to. Defaults to no file. max_iterations (int) – Maximum number of iterations to use in the iterative solver. Defaults to 100. relaxation (float) – Relaxation factor to use in the iterative solver. Defaults to 1.0. verbose (bool, optional) – Whether to output the progress of the iterative solver. Defaults to False.
Returns:	alpha – Angle of attack at the given CL.
Return type:	float

Scene Class¶

MachUpX

Navigation

Related Topics