Input File Structure

HI-Mach is run through the command line only. When himach.exe is run, the user must give an input file which specifies the geometry, flow conditions, methods, etc. This page describes the structure of the input file and the options available to the user.

Example input

HI-Mach 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 HI-Mach input file looks like the following

example_input.json

{
    "flow": {
        "freestream_direction": [ 100.0, 0.0, -10.0 ],
        "mach_number" : 6.5,
        "gamma" : 1.4,
        "altitude" : 25000
    },
    "geometry": {
        "file": "my_swept_wing.vtk",
        "reference": {
            "area": 1.0
        }
    },
    "solver": {
        "windward_method" : "modified-newtonian",
        "leeward_method" : "prandtl-meyer",
    },
    "heating": {
        "gas_model" : "tabulated",
        "use_rad_eq": false,
        "t_wall": 300,
        "streamline" : {
            "sparse" : true
        }
    },
    "output": {
        "body_file": "swept_wing_result.vtk",
        "report_file": "report.json"
    }
}

Input Specification

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

For nested settings (such as "reference" 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_direction" : [<X VELOCITY>, <Y VELOCITY>, <Z VELOCITY>],
        "mach_number" : <MACH>,
        "gamma" : <GAMMA>,
        "alpha" : <ALPHA[RAD]>,
        "beta" : <BETA[RAD]>,
        "C_L" : <LIFT COEFFICIENT>
        "altitude" : <ALTUTUDE[m]>,
        "p_inf" : <PRESSURE[Pa]>,
        "t_inf" : <TEMPERATURE[K]>
    },
...
}

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

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
freestream_direction	list of floats	one of ('freestream_direction', 'alpha', 'C_L') required	arbitrary	N/A	Oncoming freestream velocity direction expressed in the mesh (global) coordinate system. The magnitude of the vector has no effect on the solution.
alpha	float	one of ('freestream_direction', 'alpha', 'C_L') required	arbitrary	N/A	Vehicle angle of attack. If this option is specified, a nose axis and a pitch axis must be provided in the geometry section of the input file
C_L	float	one of ('freestream_direction', 'alpha', 'C_L') required	arbitrary	N/A	Required vehicle lift coefficient. HI-Mach will determine the angle of attack that results in this lift coefficient. If this option is specified, a nose axis and a pitch axis must be provided in the geometry section of the input file
beta	float	optional	arbitrary	0.0	Vehicle sideslip angle. Use in conjunction with "alpha" or "C_L" runs, if a non-zero sideslip is desired. If this option is specified, a nose axis and a pitch axis must be provided in the geometry section of the input file
gamma	float	optional	arbitrary	1.4	Freestream ratio of specific heats.
mach_number	float	required	> 1.0	N/A	Freestream Mach number.
altitude	float	either ('altitude', or 'p_inf' and 't_inf') required for viscous solutions	0-100000 in meters	0	Altitude in meters
p_inf	float	either ('altitude', or 'p_inf' and 't_inf') required for viscous solutions	positive	pressure at 0 m altitude	Pressure in Pa
t_inf	float	either ('altitude', or 'p_inf' and 't_inf') required for viscous solutions	positive	temperature at 0 m altitude	Temperature in K

Geometry

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

{
...
    "geometry": {
        "file": <PATH TO MESH FILE>,
        "file_type": <BINARY OR ASCII>,
        "mirror_about" : <MIRROR PLANE>,
        "reference": {
            "area": <AREA>,
            "length": <LENGTH>,
            "CG": [<CENTER X>, <CENTER Y>, <CENTER Z>]
        },
        "scale" : <SCALE FACTOR>
        "nose_axis": <'x-','x+','y-','y+','z-', or 'z+'>,
        "pitch_axis": <'x-','x+','y-','y+','z-', or 'z+'>,
        "curvature_cutoff": <CURVATURE VALUE>
        "waverider": {
            "cone_angle": <CONE ANGLE>,
            "shock_angle": <SHOCK ANGLE>
        }
    },
...
}

The available options for 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 HI-Mach executable). The allowable mesh file types are described in Meshes.
file_type	string	optional	ascii, binary	ascii	File type with which to read in the mesh file.
mirror_about	string	optional	xy, xz, yz		Allows the geometry to be mirrored about one of the cardinal coordinate planes within HI-Mach so that the user only has to input half of the mesh. This also leads to computational savings in some cases.
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.
scale	float	optional	non-negative	1.0	The factor by which the geometry and reference values are to be scaled.
nose_axis	string	required if flow specification given with "alpha" or "C_L"	"x+", "x-", "y+", "y-", "z+", "z-"	N/A	Direction of vector pointing out the nose, specified in mesh (global) coordinates
pitch_axis	string	required if flow specification given with "alpha" or "C_L"	"x+", "x-", "y+", "y-", "z+", "z-"	N/A	Direction of vector about which positive pitch occurs, specified in mesh (global) coordinates
curvature_cutoff	float	required if solver is "blended-curvature"	non-negative	0.0	The curvature value above which the tangent wedge method will be used
waverider		optional
cone_angle	float	optional	non-negative and less than shock_angle	0.0	Solid cone angle in radians to be used for waverider analysis
shock_angle	float	optional	non-negative	0.0	Shock angle in radians to be used for waverider analysis

Solver

The solver section specifies how HI-Mach is to solve pressures on the body:

{
...
    "solver": {
        "windward_method" : <WINDWARD METHOD>,
        "leeward_method" : <LEEWARD METHOD>,
        "shielding_effects" : <TRUE OR FALSE>,
        "base_pressure" : <BASE PRESSURE METHOD>
    },
...
}

The available options for these parameters are as follows:

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
windward_method	string	optional	modified-newtonian, straight-newtonian, tangent-cone, tangent-wedge, blended-curvature	modified-newtonian	Specifies the pressure method to be used in the windward regions of the body
leeward_method	string	optional	prandtl-meyer, none	prandtl-meyer	Specifies the pressure method to be used in the leeward regions of the body
shielding_effects	logical	optional	true, false	true	Specifies whether shielding effects are to be considered in pressure calculations
base_pressure	string	optional	gaubeaud, vacuum, none	gaubeaud	Specifies the pressure method to be used in the base regions of the body

Heating

The solver section specifies how HI-Mach is to calculate the viscous forces and convective heating. This section is optional:

{
...
    "heating": {
        "props_file" : <PROPERTY FILE LOCATION>,
        "gas_model": <GAS MODEL>,
        "use_rad_eq" : <TRUE OR FALSE>,
        "eps_wall" : <WALL EMISSIVITY>,
        "t_wall" : <WALL TEMPERATURE>,
        "boundary_layer_model" : <BOUNDARY LAYER MODEL>,
        "streamline" : {
            "sparse" : <TRUE OR FALSE>
        }
    },
...
}

The available options for these parameters are as follows:

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
use_rad_eq	boolean	optional	True or False	False	Specifies whether to use radiation equilibrium for the wall condition
eps_wall	float	optional	0.0-1.0	0.7	Specifies the emissivity of the wall for use with radiation equilibrium
t_wall	float	optional	positive	300	Specifies the wall temperature in K for use with constant wall temperature
gas_model	string	optional	'ideal' or 'tabulated'	'ideal'	The gas model to be used
props_file	string	required if gas model is 'tabulated	N/A	none	The location of the gas properties file
boundary_layer_model	string	optional	'laminar', 'turbulent', or 'transition'	'transition'	The boundary layer model to be used in heating and skin friction calculations
use_eigenvalue_attachments	boolean	optional	True or False	True	Whether to include eigenvalue-calculated attachment lines. Conical frustra are incorrectly characterized by the eigenvalue method as attachment lines
use_mangler_factor	boolean	optional	True or False	True	Whether to use the mangler factor to approximate 3d effects
streamline.sparse	boolean	optional	True or False	False	Whether to use sparse streamlines or not
streamline.streamline_file	string	optional	any		Where to write out streamlines. If left empty, no streamline file is saved

Output

The output section tells HI-Mach 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>,
        "report_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.
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.

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

More information on these output options is found in Outputs

Cases

HI-Mach input files allow for multiple cases to be run on the same geometry in rapid succession. Each case is a separate named JSON dictionary in the cases dictionary. Each case can have a flow dictionary, as specified above. Flow parameters specified in a case override flow parameters provided in the input. Cases also have an attribute that controls whether the results are written out as a .vtk file.

When HI-Mach is run with cases input, the report.json file will include results and run times from each case. If a body_file is specified in the output section, each case will write out a separate .vtk results file, unless "write_case" is specified as false.

{
   ...
   "cases": {
      "case_1" : {
         "flow":{
            "mach_number" : 5,
            "C_L" : 0.3,
            ...
         },
         "write_case": true
      }, 
      "case_2": {
         ...
      },
   ...
}

Note that each case must have a name. The following options are available for each case.

Key	Value Type	Required or Optional	Allowable Values	Default Value	Description
write_case	logical	optional	true, false	true	Whether a case should have a .vtk results body file written out.
flow	dictionary	optional	arbitrary	none	JSON dictionary of case-specific flow parameters. Structured identically to the flow section described above.

JSON Dictionary File Input

Anywhere HI-Mach requires a dictionary in the input file, the user has the option of specifying a filepath to another JSON file containing the required dictionary. For example, to supply the geometry settings in a different file, include an attribute called "filename" in the dictionary. HI-Mach will then look for the dictionary in the specified file.

{
...
    "geometry": {
        "filename": <PATH TO JSON DICTIONARY FILE>,
    },
...
}