Input File Structure

Currently, MachLine is run through the command line only. When the executable is run, the user must give an input file which specifies the geometry, flow condition, solver options, etc. This page describes the structure of the input file and the options available to the user.

Units and Coordinates

Before proceeding, we should note that MachLine is ignorant of any units of measure. It assumes that the user has given the inputs and will parse the results using a coherent unit system.

MachLine also has no native coordinate system. It simply uses the coordinates of the mesh. Thus, in the output, the force coefficient Cx denotes the nondimensional force acting in the mesh x-direction, CMx denotes the nondimensional moment about the mesh x-axis, and so forth.

Example Input

MachLine uses the common JSON file format for input. JSON files have a nested dictionary structure, where information is stored in key-value pairs. A basic MachLine input file looks like the following:

example_input.json

{
    "flow": {
        "freestream_velocity": [ 100.0, 0.0, -10.0 ]
    },
    "geometry": {
        "file": "my_swept_wing.vtk",
        "wake_model": {
            "wake_shedding_angle": 90.0,
            "trefftz_distance": 100.0,
            "N_panels": 1
        },
        "reference": {
            "area": 1.0
        }
    },
    "solver": {
        "formulation": "dirichlet-morino"
    },
    "post_processing" : {
        "pressure_for_forces": "prandtl-glauert",
        "pressure_rules": {
            "incompressible": true,
            "isentropic": false,
            "second-order": false
        },
        "subsonic_pressure_correction": {
            "correction_mach_number": 0.8399,
            "prandtl-glauert": true,
            "karman-tsien": true,
            "laitone": true
        }
    },
    "output": {
        "body_file": "swept_wing_result.vtk",
        "wake_file": "wake_result.vtk",
        "control_point_file": "control_point_result.vtk",
        "report_file": "report.json"
    }
}

Input Specification

As shown above, MachLine input files have five main parts: flow, geometry, solver, post-processing and output. We will describe each of these and the options available in turn.

For nested settings (such as "wake_model" under "geometry"), if a parent is not specified, then all its children will adopt the default values. All settings which have no default must be specified.

Flow

The flow section describes the freestream flow into which the mesh is inserted. It is structured as follows:

{
    "flow" : {
        "freestream_velocity" : [<X VELOCITY>, <Y VELOCITY>, <Z VELOCITY>],
        "gamma" : <GAMMA>,
        "freestream_mach_number" : <MACH>
    },
...
}

The available options for each of these parameters are as follows:

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
freestream_velocity	list of floats	required	arbitrary	N/A	Oncoming freestream velocity expressed in the mesh (global) coordinate system. Note the magnitude of the freestream velocity currently has no effect on the solution.
gamma	float	optional	arbitrary	1.4	Freestream ratio of specific heats.
freestream_mach_number	float	optional	non-negative	0.0	Freestream Mach number. From this and the freestream velocity, MachLine will infer the freestream speed of sound and all other relevant flow variables.

Geometry

The geometry section tells MachLine where the mesh is stored and how it should be treated. It is structured as follows:

{
...
    "geometry": {
        "file": <PATH TO MESH FILE>,
        "mirror_about" : <MIRROR PLANE>,
        "singularity_order" : <"lower" OR "higher">,
        "wake_model": {
            "wake_present" : <TRUE OR FALSE>,
            "append_wake" : <TRUE OR FALSE>,
            "wake_shedding_angle": <ANGLE>,
            "trefftz_distance": <DISTANCE>,
            "N_panels": <NUMBER OF WAKE PANELS>
        },
        "reference": {
            "area": <AREA>
        }
    },
...
}

The available options for each of these parameters are as follows:

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
file	string	required	arbitrary	N/A	Path to the mesh file (relative to the current working directory, not the location of the MachLine executable). The allowable mesh file types are described in Meshes.
mirror_about	string	optional	xy, xz, yz		Allows the geometry to be mirrored about one of the cardinal coordinate planes within MachLine so that the user only has to input half of the mesh. This also leads to computational savings in some cases.
singularity_order	string	optional	lower, higher	lower	Sets the singularity distribution type for all panels. "lower" will set linear-doublet-constant-source panels. "higher" will set quadratic-doublet-linear-source panels.
max_continuity_angle	float	optional	0.0-180.0	45.0	Maximum angle between panels before the edge is marked as discontinuous for higher-order distributions.
wake_model		optional
wake_present	logical	optional	true, false	true	Whether a wake should be assumed present. May be set to false for known nonlifting flows. However, it is typically best to leave this set to true. This should be left as true for supersonic flows where the wake does not influence the solution, as it will ensure that the doublet strength is discontinuous at edges where the wake is shed.
append_wake	logical	optional	true, false	value of wake_present	Whether or not a wake should be explicitly added to the mesh. For supersonic flows where it is known the wake will not influence the solution, this may be set to false. In all other cases or if in doubt, it is best to let this be the default. Note, this may not be set to true if wake_present is set to false.
wake_shedding_angle	float	optional	0.0-180.0	90.0	Maximum allowable flow-turning angle (in degrees) between two panels. If the angle between any two panels exceeds this value, then wake panels will be shed from the common edge.
trefftz_distance	float	optional	non-negative	mesh-dependent	Distance from the mesh origin at which the wake terminates. In the case of supersonic flows, the default value for this parameter is the distance to the most-downstream point of the mesh. For subsonic flows, the default value is 20 times the freestream distance between the most upstream and downstream points.
N_panels	integer	optional	non-negative	1	Half the number of panels distributed streamwise from each wake-shedding edge to model the wake. This is half the number of panels in each strip of the wake because the wake mesh is structured while MachLine implements only triangular panels.
reference		optional
area	float	optional	non-negative	1.0	Reference area for non-dimensionalizing reported aerodynamic coefficients.
length	float	optional	non-negative	1.0	Reference length for non-dimensionalizing reported aerodynamic coefficients.
CG	vector	optional	arbitrary	[0.0, 0.0, 0.0]	Center of gravity location described in mesh coordinates. The reported moment coefficients will be about this point.

Solver

The solver section specifies how MachLine is to solve for the source and doublet strengths which unqiuely specify the flow field. It is structured as follows:

{
...
    "solver": {
        "formulation" : <FORMULATION>,
        "control_point_offset" : <DISTANCE>,
        "control_point_offset_type" : <'direct' OR 'local'>,
        "run_checks" : <TRUE OR FALSE>,
        "matrix_solver" : <SOLVER>,
        "relaxation" : <RELAXATION FACTOR>,
        "tolerance" : <TERMINATION TOLERANCE>,
        "block_size" : <BLOCK SIZE>,
        "max_iterations" : <MAXIMUM SOLVER ITERATIONS>,
        "preconditioner" : <PRECONDITIONING METHOD>,
        "write_A_and_b" : <TRUE OR FALSE>,
        "sort_system" : <TRUE OR FALSE>,
        "iterative_solver_output" : <FILENAME>
    },
...
}

The available options for these parameters are as follows:

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
formulation	string	optional	dirichlet-morino, dirichlet-source-free, neumann-mass-flux, neumann-velocity	dirichlet-morino	Specifies the formulation which is to be used for enforcing boundary conditions. You can learn more about these formulations here.
control_point_offset	float	optional	positive	1e-7	Distance at which control points are to be offset from the body surface. The direction of offset is dependent upon the formulation. As such, this value should always be positive.
control_point_offset_type	string	optional	'direct', 'local'	'direct'	Method for offsetting control points from the mesh surface. 'direct' specifies the length of offset directly. If 'local' is selected (not recommended), then the offset given above is the ratio of the offset distance to the average of all neighboring edge lengths.
run_checks	logical	optional	true, false	false	Specifies whether certain checks as to the solvability of the specified problem are to be made. Useful when debugging.
matrix_solver	string	optional	GMRES, QRUP, LU, BJAC, BSOR, PURC	GMRES	Specifies which matrix solver is to be used for solving the linear system of equations. You can learn more about these matrix solvers here.
relaxation	float	optional	0.0 < relaxation < 2.0	0.5	Relaxation factor used in the iterative matrix solvers.
tolerance	float	optional	arbitrary	1e-10	Norm of the residual at which the iterative matrix solvers will terminate.
block_size	integer	optional	arbitrary	100	Block size for performing block iterative matrix solvers.
max_iterations	integer	optional	arbitrary	1000	Maximum number of iterations for the iterative matrix solvers.
preconditioner	string	optional	NONE, DIAG	DIAG	Specifies the preconditioning method to use on the linear system. DIAG will precondition the system with the diagonal elements of A.
write_A_and_b	logical	optional	true, false	false	If set to true, MachLine will write out the linear system to the files "A_mat.txt" and "b_vec.txt". Useful when debugging.
sort_system	logical	optional	true, false	true	Specifies whether the linear system of equations should be sorted based on vertex location. This is necessary for the QRUP and FQRUP solvers. It may also positively affect the performance of other solvers, and so is perfromed by default.

Post-Processing

This is where pressure calculations are specified. It is structured as follows:

{
...
    "post_processing" : {
        "pressure_rules": {
            "incompressible": true,
            "isentropic": false,
            "second-order": false
        },
        "subsonic_pressure_correction": {
            "correction_mach_number": 0.8399,
            "prandtl-glauert": true,
            "karman-tsien": true,
            "laitone": true
        },
        "pressure_for_forces": "prandtl-glauert"
    },
...
}

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
pressure_rules		optional			See Pressure Rules.
incompressible	logical	optional	true, false	true if M=0, false otherwise	Whether the incompressible pressure rule is to be used for surface pressure calculations.
isentropic	logical	optional	true, false	true if M>0, false otherwise	Whether the isentropic pressure rule is to be used for surface pressure calculations.
second-order	logical	optional	true, false	false	Whether the second-order pressure rule is to be used for surface pressure calculations.
slender-body	logical	optional	true, false	false	Whether the slender-body pressure rule is to be used for surface pressure calculations.
linear	logical	optional	true, false	false	Whether the linear pressure rule is to be used for surface pressure calculations.
subsonic_pressure_corrections		optional
correction_mach_number	float	optional	>=0.0	0.0	Freestream Mach number used to correct incompressible pressure coefficients for compressibility.
prandtl-glauert	logical	optional	true, false	false	Whether to use the Prandtl-Glauert rule to correct pressure coefficients for compressibility.
karman-tsien	logical	optional	true, false	false	Whether to use the Karman-Tsien rule to correct pressure coefficients for compressibility.
laitone	logical	optional	true, false	false	Whether to use the Laitone rule to correct pressure coefficients for compressibility.
pressure_for_forces	string	optional	incompressible, isentropic, slender-body, second-order, linear, prandtl-glauert, karman-tsien, laitone	Varies	Specifies which pressure is to be used for total force integration. The default is the highest-order pressure rule which has been specified for the given freestream condition. See Pressure Rules.

Output

The output section tells MachLine where to store the solver results. It is structured as follows:

{
...
    "output": {
        "verbose" : <TRUE OR FALSE>,
        "body_file" : <PATH TO FILE>,
        "mirrored_body_file" : <PATH TO FILE>,
        "wake_file" : <PATH TO FILE>,
        "control_point_file" : <PATH TO FILE>,
        "report_file" : <PATH TO FILE>,
        "offbody_points" : {
            "points_file" : <PATH TO FILE>,
            "output_file" : <PATH TO FILE>
        }
    }
}

The available options for these parameters are as follows:

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
verbose	logical	optional	true, false	false	Whether solver messages should be written to the terminal during execution.
body_file	string	optional	arbitrary	none	File location where the surface mesh results should be stored. If not given, surface mesh results will not be stored.
mirrored_body_file	string	optional	arbitrary	none	File location where the mirrored surface mesh results should be stored. If not given, mirrored surface mesh results will not be stored.
wake_file	string	optional	arbitrary	none	File location where the wake mesh results should be stored. If not given, wake mesh results will not be stored.
control_point_file	string	optional	arbitrary	none	File location where the control point results should be stored. If not given, control point results will not be stored.
mirrored_control_point_file	string	optional	arbitrary	none	File location where the mirrored control point results should be stored. If not given, mirrored control point results will not be stored.
report_file	string	optional	arbitrary	none	File location where a report on the output of the solver will be stored. If not given, a report will not be generated. Must have the .json extension.
offbody_points		optional
points_file	string	optional	arbitrary	none	File location containing a list of points at which MachLine is to calculate velocity potentials and velocities. Must be formatted as comma-separated values. Each line is one point (i.e. `X,Y,Z`). MachLine assumes this file has a one-line header.
output_file	string	optional	arbitrary	none	File location to write velocity potentials and velocities to. These will be calculated at the points specified in `points_file`.

All these should be paths to the desired file relative to the current working directory, not the location of the MachLine executable.

These outputs are generated after the solver finishes exectution, and will give the pressure, doublet strength, source strength, and velocity distributions on the mesh. However, if the solver fails to execute and a body, wake, or control point file are specified, the MachLine will still output these geometries to the specified files. This allows the user to inspect the meshes parsed/generated by MachLine and discover potential causes for solver failure.

If any of these file locations is specified, MachLine will delete any existing files with the same name before writing new data, even if there is no data to write. For example, suppose the user has specified a wake file output as "wake.vtk". From a previous run, there is already a file in the current working directory called "wake.vtk". On this run, whether or not a wake is automatically generated, "wake.vtk" will be deleted. If a wake is automatically generated, then an entirely new file will be written. Do not reuse output file names unless you are fine with all old data being lost.

More information on these output options is found in Outputs.

Home | Installation | Input File Structure | Modeling | Support