e3prep (Application)

Python program to specify the flow problem.

This program takes the userinput, in the form of a Python script, and generates the files needed to start a simulation. There are a number of functions that may be called by the user’s script.

Usage

It is intended for the user to define the flow simulation in terms of the data objects defined in this program. As part of its initialization, e3prep.py will execute a user-specified job file that contains, in Python, the user’s script that defines both geometry and flow details.

The flow simulation definition is organised via the classes: GlobalData2D, FlowCondition, HeatZone, SimplePiston, Block2D and Block3D. These classes provide places to store the configuration information and their function (or method) names appear as commands in the job description file. See the __init__() method for each class to determine what parameters can be specified when creating an object of that class.

The user will define the particular geometry in terms of the data objects defined in the geom and gpath modules. This geometry definition is created in a bottom-up approach by successively defining Nodes, simple path elements (such as Line, Arc and Bezier elements) and, possibly, compound path elements (such as Spline objects and Polyline objects). In 2D flow, four paths are then used to define a patch over which a block of finite-volume cells is defined. The four bounding faces of each Block2D object also carry boundary-condition information. In 3D flow, there will be 6 bounding surfaces for each Block3D object.

Note that physical quantities should be specified in MKS units.

Command line:

e3prep.py [options]

Options:

| e3prep.py [--help] [--job=<jobFileName>] [--clean-start]
|           [--do-svg] [--do-vrml] [--zip-files|--no-zip-files]
|           [--show-names] [--split-input-file] [--verbosity=<int>]

Example

  • Prepare the simulation input files along with a scalable-vector-graphic representation of the 2D flow domain:

    e3prep.py --job=cone20 --do-svg
    
  • There are many details to preparing the input script. Study the User Guide and the many examples contained therein.

Notes

  • Files that are generated will have names constructed with jobFileName as the root.
  • The SVG file, with some careful editing, will be useful for documentation of your simulation. It includes annotated boundary conditions.
  • The 3D equivalent is to geerate a VRML file. (Needs work.)
  • These days, the default behaviour is to have individual blocks split into individual times and read/write gzip-compressed solution files.

Globally-defined objects

  • gdata: Contains the GlobalData information describing the simulation. Note that there is one such variable set up by the main program and the user’s script should directly set the attributes of this variable to adjust settings for the simulation.
  • sketch: A global variable holding the state of the SketchEnvironment. Note that there is one such variable set up by the main program and the user’s script should directly set the attributes of this variable to adjust settings (such as scale and ranges of the axes) for the SVG output.

Functions and classes for use in your input script

e3prep.select_gas_model(model=None, species=None, fname=None)

Selects a gas model for the simulation.

Parameters:
  • model – (string) name of the gas model as shown in the list below.
  • species – list of species names (strings). Note that you could also provide a dictionary with species names as keys and mass-fraction values (and the mass-fractions will be ignored).
  • fname – (string) name of the gas-model file.
Returns:

a list of species names.

The new gas models are configured by stand-alone files. This function initialises a gas model for present use in the preparation program (ie. sets it in kernel code) and stores the name for later user at simulation time.

If you already have a gas-model.lua file already set up, give its name af fname.

If you have not already set up the gas-model.lua file, this function is provided as a simple but limited means to do so.

Look-up-table (LUT) gas models and LUT_plus_composite cannot be created directly with this function. If you want a single LUT gas model, just set up the LUT table file externally and supply the name of that file as fname. If you want a LUT-plus-composite gas model, set up the LUT table externally and then set up the rest of the composite gas model using create_gas_file() directly, then select the gas model by specifying the gas file name when calling this function. The create_gas_file() function has the capability of prepending the LUT gas species to the composite gas species list.

e3prep.set_reaction_scheme(fname, reacting_flag=1, T_frozen=300.0)

Sets the reaction update model and specifies a reacting simulation.

Parameters:
  • fname – (string) the name of the input file for the reaction update.
  • reacting_flag – (int) 1=reacting, 0=nonreacting
  • T_frozen – (float) temperature (in K) below which reactions are frozen
Returns:

None

Note that the user may later reset that flag within the input script, possibly to turn off reactions for a particular simulation.

e3prep.set_energy_exchange_scheme(fname, energy_exchange_flag=1, T_frozen_energy=300.0)

Sets the energy exchange update model and specifies a TNE simulation.

Parameters:
  • fname – (string) the name of the input file for the energy exchange update.
  • energy_exchange_flag – 1=do exchange; 0=no exchange
Returns:

None

Note that the user may later reset the flag, possibly to turn off energy exchange for a particular simulation.

e3prep.select_radiation_model(input_file=None, update_frequency=1, scaling=True)

Selects the radiation spectral and transport models for the simulation.

Parameters:
  • input_file – (string) name of the radiation configuration file
  • update_frequency – (int)
Returns:

None, or may exit the program if input_file is not specified.

This function is provided to the user as a means to setup a radiation model. It initialises a radiation model for present use in the preparation program (ie. sets it in kernel code) and stores the name for later user at simulation time.

class e3prep.GlobalData

Organise, remember and write the global data.

The user’s script should not create one of these but should specify the simulation parameters by altering the attributes of the one instance of this global object, gdata.

  • title: (string) A piece of text that will be propagated through the solution files and subsequently generated plots.
  • case_id: (int) An identifier for special cases in which pieces of specialised code have been embedded into the main simulation program. If you don’t have such code to activate, the default value of 0 is fine.
  • gas_model_file: (string) The input file required for configuring the gas model
  • axisymmetric_flag: (0/1) A value of 0 sets two-dimensional, planar flow. A value of 1 sets axisymmetric flow with the x-axis being the axis of symmetry.
  • viscous_flag: (0/1) Set to 1 to activate viscous transport terms. Set to 0 (the default) for inviscid flow simulation.
  • separate_update_for_viscous_flag: (0/1) Set to 1 to have the update for the viscous transport terms done separately to the convective terms. Set to 0 (default) to have the viscous-term updates in the same explicit update stages as the convective terms.
  • viscous_delay: (float) Sometimes, the viscous terms make it difficult to start a calculation without encountering numerical instability. Set this parameter to the delay (in seconds) from simulation start to the time at which the viscous terms will be allowed to become active (if L{viscous_flag} was set to 1).
  • viscous_factor_increment: (float) Increment for the viscous_factor after viscous_delay has passed.
  • diffusion_flag: (0/1) Set to 1 to compute multi-component diffusion of species
  • diffusion_model: (string) set the type (by name) of multi-component diffusion model
  • diffusion_delay: (float) Sometimes, the diffusion terms make it difficult to start a calculation without encountering numerical instability. Set this parameter to the delay (in seconds) from simulation start to the time at which the diffusion terms will be allowed to become active (if L{diffusion_flag} was set to 1).
  • diffusion_factor_increment: (float) Increment for the diffusion_factor after diffusion_delay has passed.
  • diffusion_lewis_number: (float) Lewis number used in the constant Lewis number diffusion model, default 1.0
  • diffusion_schmidt_number: (float) Schmidt number used in the constant Schmidt number diffusion model, default 0.7
  • turbulence_model: (string) “none” (default), “baldwin-lomax”, “k-omega”, “spalart-allmaras”
  • turbulence_prandtl_number: (float) default 0.89
  • turbulence_schmidt_number: (float) default 0.75
  • max_mu_t_factor: (float) Limiting factor for the turbulence viscosity relative to the laminar viscosity.
  • transient_mu_t_factor: (float) A value of 1.0 indicates a fully-developed turbulent flow. Set values less than 1.0 to model transient flows where the turbulence is not fully developed. This may be good for Matt McGilvray’s scramjet experiments in the expansion tube which have very short flow durations.
  • separate_update_for_k_omega_source: (boolean) By default, the k-omega source terms will be integrated in with the viscous and convective explicit update. Setting this True will allow separate update of the k-omega source terms with with a more robust integrator.
  • heat_time_start: (float) start time for heating zones to be adding energy
  • heat_time_stop: (float) final time for heating zones to be adding heat
  • heat_factor_increment: (float) the fraction of full heat load that will be added with each time step from t=heat_time_start
  • ignition_time_start: (float) start time for using an effective ignition temperature for chemistry updates
  • ignition_time_stop: (float) final time for using an effective ignition temperature for chemistry updates
  • reacting_flag: (0/1) A value of 1 will make Rowan Gollan’s finite-rate chemistry active if the appropriate gas_name (e.g. ‘perf_gas_mix’) has been specified.
  • T_frozen: (float) temperature (in K) below which reactions are frozen.
  • reaction_time_start: (float) Time after which reactions are allowed to proceed.
  • reaction_update: (string) A (file) name for the chemical kinetics scheme
  • energy_exchange_flag: (0/1) A flag indicting finite-rate evolution of thermal state
  • energy_exchange_update: (string) A (file) name for the thermal energy exchange scheme
  • T_frozen_energy: (float) temperature below which the energy-exchange will be skipped.
  • x_order: (int 1 or 2) Specifies the form of reconstruction from cell-average data to cell interface data. Select 1 for low-order (i.e. no) reconstruction. Select 2 for a higer-order (limited quadratic) reconstruction.
  • gasdynamic_update_scheme: (string) one of “euler”, “pc”, “predictor-corrector”, “midpoint”, “classic-rk3”, “tvd-rk3”, “denman-rk3”
  • t_order: [deprecated, use gasdynamic_update_scheme instead] (int 1 or 2) Specifies the form of time stepping scheme. Select 1 for Euler stepping. Select 2 for predictor-corrector stepping.
  • stringent_cfl: (0/1) Set to 1 to get a very strict CFL check.
  • flux_calc: (int or string) Specifies the form of flux calculation at cell interfaces. Options are “riemann”, “ausm”, “efm”, “ausmdv”, “adaptive”, “ausm_plus_up”, “hlle” and “hllc”. default “adaptive”
  • compression_tolerance: (float) relative velocity change for the shock detector. This value is expected to be a negative number (for compression) and not too large in magnitude. default -0.30
  • shear_tolerance: (float) normalised tangential velocity change beyond which we we suppress the application of EFM in the ADAPTIVE flux calculator. default 0.20
  • M_inf: characteristic free-stream Mach number for the ausm_plus_up flux calculator. default 0.01
  • interpolation_type: (string) Choose the set of thermo variables to use in interpolation. options: “rhoe”, “rhop”, “rhoT”, “pT”, default “rhoe”
  • interpolate_in_local_frame: (bool) Set True to have reconstruction done in the interface-local coordinate frame, use global coordinate frame otherwise. Default is True.
  • apply_limiter_flag : (0/1) Set to 1 to have reconstruction limiter enabled (default) Set to 0 for no limiting
  • extrema_clipping_flag : (0/1) Set to 1 to allow clipping of extreme values in the 1D scalar reconstruction function (default). Set to 0 to suppress clipping.
  • overshoot_factor : default 1.0. Relax extrema clipping by setting greater than 1.0.
  • dt: (float) Size of the initial time step. After a few steps, the solver will have enough information to select a suitable time step, based on the cfl number.
  • dt_max: (float) Size of the maximum allowable time step. Sometimes, especially when strong source terms are at play, the CFL-based time-step determination does not suitably limit the size of the allowable time step. This parameter allows the user to limit the maximum time step directly.
  • cfl: (float) The ratio of the actual time step to the allowed time step as determined by the flow condition and grid. Typically the default value of 0.5 is good but you may want to try smaller values if you are having the solution go unstable, especially for viscous simulations.
  • viscous_signal_factor: (float) 1.0==full viscous effect for the signal calculation within the time-step calculation. It has been suggested that the full viscous effect may not be needed to ensure stable calculations for highly-resolved viscous calculations. A value of 0.0 will completely suppress the viscous contribution to the signal speed calculation.
  • print_count: (int) The number of time steps between printing a status message to the console.
  • cfl_count: (int) The number of time steps between checking the CFL number.
  • fixed_time_step: (boolean) Flag to indicate fixed time-stepping
  • max_invalid_cells: (int) Number of cells that will be tolerated without too much complaint.
  • dt_reduction_factor: (float) If a time step fails because of any bad cells, this is the factor to reduce the size of the next attempted time step.
  • max_time: (float) The (simulation) time (in seconds) at which time stepping should be terminated.
  • max_step: (int) Time stepping will be terminated if the simulation reached this number of steps.
  • halt_on_large_flow_change: (bool) If True, we want the simulation to halt if the flow changes significantly at any of the MonitorLocations (or mcells)
  • tolerance_in_T: (float) allowable change in Temperature before the simulation will be halted.
  • shock_fitting_flag: (0/1) Set to 1 to activate adaptation of the grid to the shock. Set to 0 (the default) for no shock adaptation. Note that shock-fitting implies a moving grid so moving_grid_flag will also be set.
  • shock_fitting_speed_factor: (float) The calcuated boundary interface velocity is multiplied by this number. It may need to be reduced below the default of 1.0 for stability on fine grids.
  • shock_fitting_decay_flag: (0/1) Set to 1 to cause the shock fitting speed factor to decay exponentially from the given value to 0 over the length of the simulation. Set to 0 (the default) for no decay.
  • moving_grid_flag: (0/1) Set to 1 to activate functions that allow the grid to move. Set to 0 (the default) for a static grid.
  • write_vertex_velocities_flag: (0/1) Set to 1 to write the vertex velocities to file. Set to 0 (the default) for no files.
  • filter_flag: (0/1) Set to 1 to periodically apply a flux corrected transport filter consisting of a diffusion and an anti-diffusion step. Set to 0 (the default) for no filtering
  • filter_tstart: (float) Time at which to start filtering.
  • filter_tstop: (float) Time at which to stop filtering.
  • filter_dt: (float) Period (in seconds) between applying the FCT filter.
  • filter_mu: (float) Amount of diffusion to apply when filtering. 0.0 is no diffusion, 1.0 replaces the cell information with the average of the adjacent cells.
  • filter_npass: (int) Number of passes of the filter to apply at each interval.
  • dt_moving: (float) Period (in seconds) between running the setting vertex velocity for moving grid.
  • dt_plot: (float) Period (in seconds) between writing all of the flow field data to the solution files. Multiple instances, each with a specific time stamp/index, can be written for one simulation so be careful not to write too many and fill up your disk. The .times files records the instances written so you can look up the content of that file to see the map between time index and actual simulation time.
  • dt_history: (float) Period (in seconds) between writing the data for the selected cells to the history files.
  • write_at_step: (int) Update step at which flow field data will be written. To distinguish this data set from the regularly written with dt_plot, the index tag for this solution is “xxxx”. Leave as the default value 0 to not write such a solution.
  • conjugate_ht_flag: (0/1) A flag indicating if the conjugate heat transfer at NORTH wall is active
  • conjugate_ht_file: (string) A (file) name for the configuration of the wall conduction model if the conjugate heat transfer model is active.
  • conjugate_ht_coupling: (string) Indicate coupling mode between fluid and solid.
  • wall_update_count: (int) Number of steps to wait before recomputing heat transfer in the wall conduction model. Values greater than 1 give a loosely-coupled approach to the flow solver/ wall solver update.
  • flow_induced_moving_flag: (0/1) Set to 1 to activate functions that allow flow induced grid movement.
  • cfl_moving: (float) The ratio of the actual time step to the allowed time step as determined by the vertex moving velocity and grid.
  • wall_function_flag: (0/1) Set to 1 to activate wall functions. Set to 0 (the default) for a low Reynolds model.
  • artificial_diffusion_flag: (0/1) Set to 1 to activate the artificial diffusion. Set to 0 (the default) to turn it off.
  • artificial_kappa_2: the coefficient for the second order artificial dissipation term.
  • artificial_kappa_4: the coefficient for the fourth order artificial dissipation term.
class e3prep.HeatZone(qdot, point0, point1, label='')

Organise the description for heat-addition zones.

Each zone is intended to model energy deposition into the flow domain maybe approximating a electric spark.

__init__(qdot, point0, point1, label='')

Sets up a hexahedral heat-addition zone defined by its diagonal corner points.

Parameters:
  • qdot – (float) rate of heat addition in W/m**3
  • point0 – (Vector) lower corner of the zone
  • point1 – (Vector) upper corner of the zone

Note that it doesn’t matter if the defined zone extends outside of a block because of the way the test is done within the source terms.

class e3prep.ReactionZone(point0, point1, label='')

Describe the zones in which finite-rate reactions are allowed.

These zones will be used to set a flag contained within each finite-volume cell of the main simulation.

__init__(point0, point1, label='')

Sets up a hexahedral heat-addition zone defined by its diagonal corner points.

Parameters:
  • point0 – (Vector) lower corner of the zone
  • point1 – (Vector) upper corner of the zone

Note that it doesn’t matter if the defined zone extends outside of a block.

class e3prep.TurbulenceZone(point0, point1, label='')

Describe the zones in which the turbulence models are active.

These zones will be used to set a flag contained within each finite-volume cell of the main simulation.

__init__(point0, point1, label='')

Sets up a hexahedral turbulent-addition zone defined by its diagonal corner points.

Parameters:
  • point0 – (Vector) lower corner of the zone
  • point1 – (Vector) upper corner of the zone

Note that it doesn’t matter if the defined zone extends outside of a block.

Table Of Contents

Previous topic

Eilmer3

Next topic

e3post (Application)

This Page