EngSim doc
Bruce Bowling
bowling at cebaf.gov
Thu Apr 6 01:13:06 GMT 1995
EngSim V 0.50
User's Manual
Bruce Bowling
April 03, 1995
I. Introduction
---------------
EngSim (pronounced N-SIM) is a dynamic engine simulator which provides the user
with engine operational information and data. The code was designed to provide
dynamical representations of engines under differing environmental conditions.
This code will be eventually be used to provide simulated engine running
conditions for various engine management algorithms. The code for EngSim
can be distributed freely, with the original author and source intact.
II. EngSim Theory Of Operation
------------------------------
EngSim is a time-oriented dynamical model in which controlling and
controlled parameters can be set by the user. The simulation is based
on a crankshaft incrementation value, which is an input by the user. This
increment value determines the time-step of the simulation. Therefore,
a simulated engine with an crankshaft increment value of 1 degree, running
at 1000 RPM, will have a greater time increment (1.6e-4 seconds) than the
same engine turning at 7000 RPM (2.3e-5 seconds). This leads to the fact
that engines simulated at higher RPMs will take require longer EngSim
execution times than the equivalent engine at a slower RPM. The "running"
time of a simulated engine is based on total seconds, an user input.
Initial simulation time, initial crankshaft angle, initial engine
RPM and rate of change RPM (RPMDOT) are alterable from the default
state (see below). The initial camshaft angle is also user-defined,
and this is the place one can set the camshaft installation advance/retard
angle relative to crank angle.
There are several engine-defined inputs which will require user-inputs. (It
should be noted that the default values chosen match a Chevrolet 350
engine owned by the author) These include engine CID (cubic inch
displacement), piston diameter, connecting rod length, crankshaft
stroke, and number of cylinders. EngSim assumes cylindrical symmetry
(i.e. all cylinders are identical), so one only has to input info
on one cylinder and EngSim will do the work of duplication.
Camshaft inputs are based on cam manufacturer's data sheet, which
include intake lobe centerline, intake/exhaust lobe separation,
and lifts at baseline, 0.050, and max lift. It is assumed that
all intake and all exhaust lobes are identical, and that symmetric
ramp patterns are used. EngSim uses a "relaxed" (natural) cubic
spline fit on the input data, resulting in a continuous "lobe".
(Splines were chosen over Legendre polynomials mainly due to
the sparse information available on camshaft sheets).
Once the inputs are parsed and munged-upon, EngSim starts execution.
The user can select different parameter groups for printout. Be
warned that EngSim can produce vast amounts of output very quickly,
especially at fine crankshaft increments and high crankshaft RPMs.
One very power feature of EngSim is the use of "events". An event
is a condition when one variable controls the value of another.
For instance, it may be desirable to change engine RPMs during a
simulation run based on specific trigger times . The event mechanism
allows this to occur. The inputs are the controlled variable with
controlling event points, and the controlled variable with corresponding
values. Other uses for events are controlling engine coolant temperature
over time, tracking engine RPM with throttle, letting throttle
change rates to control vacuum changes, etc.
III. Compiling EngSim
---------------------
EngSim was written in non-ANSI "C", and will compile on many of
the C compilers floating around. The author has successfully
compiled the code using the generic Unix "cc", and the GNU "gcc"
compilers. One must link in math libraries to handle the
transcendential functions used in EngSim. Unix syntax:
gcc -o engsim engsim.c -lm
with gcc being replaced with "cc", or c68k, etc. There is nothing
exotic about the code, so compiling on a PC should be straight-forward.
But there are no guarantees. Let the author know what problems occur
in compiling, so they can be fixed on future releases.
IV. User Inputs
---------------
General Inputs:
For the current release of EngSim, the simulation control file is
named "simfile" and must exist in the same directory as the EngSim
executable. An error will occur if the file is not where EngSim
wants it to be. If you want to use all default settings, make
a "simfile" with nothing inside of it, to fool EngSim.
For general inputs, the file format is of the form:
variable value
One can put an equals sign if one wants to, for example
variable = value
There can be blank lines in the file, they will be ignored. One can
also put in text, as long as the first word does not match a variable
or keyword, such as "event" or "t0" (see below). But I advise against it.
Variables will assume the default value if they are not entered in this
file, so a lot of the time-based initialization values will not
usually be entered. The ordering of the appearance of general inputs
is irrelevant (not true with events, see below).
Remember: Garbage in, garbage out.
The following are the available user inputs understood by EngSim:
t0 (time) - Initial starting time in seconds. Default is 0.0, and
this is a good number to use, unless you know what you
are doing (which the author does not).
crankang0 - Initial crankshaft angle in degrees, from 0.0 to 720.
Default is 0.0, so use it!
camang0 - Initial camshaft angle in degrees, relative to the
crankshaft initial angle. If the camshaft simulated
is installed "straight-up", with no advance or retard,
then the default value of 0.0 is great. This is the
place to enter in the global camshaft starting angle
relative to the crank.
rpm0 - Initial engine RPM, in revs/minute. The default is
1000 RPM, so if you are lucky this may work for you,
otherwise change it. If you enter 0.0 for an RPM,
besides being a dumb input for a dynamical simulation,
it can cause the simulation to crash or better yet
"hang" in an infinite loop which may still be spewing
output to the disk, eventually filling the disk up
and crashing the computer. You were warned.
rpmdot0 - Initial Rate-of-change of RPM, in RPMs/seconds. Default
setting is 0.0, 99% of time this is what you need.
crankanginc - Crankshaft angle increment value for simulation. This
value is used as a controller on crankshaft resolution.
Smaller increment angles will yield a finer resolution,
but will increase computation time. The default of
1 degree works well for most uses.
tend - Simulation ending time, in seconds. This is the value
which determines the running time (simulation seconds)
and must be greater than any time-related events in
order for the event to occur. If this value is not
set, EngSim will determine a value internally which
will produce a run of two crankshaft revolutions at
the given (or default) RPM. If a high number is
given, like 1000000 seconds, be prepared to wait a
lifetime for the results, perhaps shorter when the
disk crashes because the printout options had been set.
prnang - Determines how often a printout line will occur, for
the user-chosen outputs, in crankshaft degrees. For
example, if the crankanginc is set to 1.0, and the
prnang is set to 2.0, a printout line(s) will occur
every 2 crank degrees. The resolution is in
crankanginc degrees, so if one set crankanginc to
90 degrees, and prnang to 1.0 degrees, a printout
line will occur at 90 degrees. It makes more
sense when used the other way: if crankanginc is
set to 1.0 degrees, and prnang is set to 90. degrees,
the printout will still occur at 90 degree increments,
but the simulation internals will operate at the finer
resolution of 1.0 degree. Enough!
cid - Engine cubic inch displacement. 350 is the obvious default.
ncyl - Number of cylinders. One can use any number, as long
as it is 4, 6, or 8.
bore - Cylinder bore in inches. Default is 4.0
stroke - Crankshaft stroke in inches (default = 3.75)
rlen - Connecting rod length from center of big end to center
of little end. Default is 7.50
Cylinder_1_fireorder - Engine firing order. Determines piston position
Cylinder_2_fireorder offset and cam timing in the internals. Default:
Cylinder_3_fireorder (1,2,3,4,5,6,7,8) respectively. If you put in
Cylinder_4_fireorder something stupid, stupid things will result.
Cylinder_5_fireorder
Cylinder_6_fireorder
Cylinder_7_fireorder
Cylinder_8_fireorder
cam_in_cl - Camshaft intake lobe centerline, referenced in crank degrees
from TDC exhaust/intake stroke boundary. The default value
is 106.0 degrees CRANK.
cam_lobe_sep - Camshaft intake-exhaust lobe separation, in CAMSHAFT degrees.
I did not come up with this screwy referencing angle scheme -
this is how it is done by many cam manufacturers. The
default is 110. CAM degrees.
cam_in_dur - Advertised intake valve duration, in degrees crank. Default
is 270.0
cam_in_dur050- Intake valve duration at 0.050 CAMSHAFT lift. Just get it
off the camshaft card given with the cam. Default = 224.
cam_ex_dur - Like cam_in_dur, except for exhaust. Same default.
cam_ex_dur050- Like cam_in_dur050, except for exhaust. Same default.
rocker_ratio - Rocker arm ratio. Default is 1.5
cooltemp - Coolant Temperature in degrees F, even though nothing really
depends on this unit. Default is a toasty 160.
cooltempdot - Rate-of-change of variable cooltemp, default is zero.
cool2cvtslp - One can perform a linear translation of the coolant temperature
to some other units. For instance, if one measured the resistance
of a temperature transducer and a function of temperature, found
the slope and offset values of the linear transfer function,
the slope part is entered here. This and the following variables
(all with "2cvt" in the name) are provided for convience.
The slope and offset (see below) yield a system variable "cool2cvt":
cool2cvt = cool2cvtslp * cooltemp + cool2cvtoff
The default is something stupid.
cool2cvtoff - The offset part of the user-defined transfer function (see above).
Default is something.
carbtemp - Air intake temperature, historically the air sucked through the
carburetor. Units are degrees F, and the default is 60 degrees.
carbtempdot - Another rate-of-change variable, this time affecting carbtemp.
The "dot" on the variable indicates a time derivative, in this
case time in seconds. So a value of 10.0 represents a change
in carbtemp of +10.0 degrees per second, like driving into an oven.
Default is 0.00000000
carb2cvtslp - See "cool2cvtslp".
carb2cvtoff - See "cool2cvtoff". The equation creating carb2cvt is:
carb2cvt = carb2cvtslp * carbtemp + carb2cvtoff
throttle - Throttle plate opening in degrees, usually between 5 and 89 degrees.
Default = 5.0. Nothing (yet) depends on the throttle position,
but one can tie in events that control this value based on time.
Soon, EngSim will have airflow stuff, so changes in throttle
will change RPM, vacuum, etc. But for now, the user must tie
these together, using events.
throttledot - How fast you mash down on the accelerator. 0 is the startup.
th2cvtslp - See "carb2cvtslp".
th2cvtoff - See "carb2cvtoff". Equation for final "th2cvt" variable:
th2cvt = th2cvtslp * throttle + th2cvtslp
vacuum - Intake manifold vacuum, in Kpa. Nice units.
vacuumdot - How much the vacuum changes over time, default is zero.
vac2cvtslp - see "th2cvtslp".
vac2cvtoff - see "th2cvtoff". Governing equation:
vac2cvt = vac2cvtslp * vacuum + vac2cvtoff
Events
What are events? They are a convienent means of changing the value of a variable
as a step function of another. One can see setting up a run which runs the
engine at different RPMs, or changes the throttle position, etc. Most events
are time related, so that the passage of time tiggers the change in a variable.
EngSim only allows the changing of variable as a function of time, but soon
EngSim should allow any variable to affect any other variable. But not now.
Lets peer into a event setup, as inputted in "simfile", with correct syntax:
event
t 0. 1. 2. 3.
rpm 2000. 3000. 1500. 2000.
endevent
the keyword of "event" all alone indicates the specification of an event.
There has to be a corresponding "endevent" keyword to close out and complete
the event. If you leave out this keyword, something very bad will happen,
I just do not know what.
The line "t 0. 1. 2. 3." indicates the "controller" variable, in
this case time (t is the variable in the input specifications). The current
version of EngSim only allows time as the controller variable, and the first
line is always the controller variable, so always (until told otherwise)
put in "t" in the first line. The numbers are the event time, so something
shall happen after 1 second, then something else should happen after 2 seconds,
etc. These are the time events.
The line "rpm 2000. 3000. 1500. 2000." represents the "controlled" events.
the variable controlled is rpm. The number corresponds to the associative
event number above, and indicates what the value should be when the event
happens. In the example, out of the hole (t=0.), the rpm is 2000. It
ramps up at a rate which yields 3000 rpm at t=1 second. The rpm then
linearly ramps down to 1500 at t=2 seconds, then finally ramp to 2000
rpm at t=3 seconds (remember t is simulation time). After 3 seconds,
the rpm is held steady at 2000 rpm until the end of the run.
The change in rpm, in this case, is computed in the event section of the
code. It changes the rpm value itself at each time step, not using the
rpmdot variable. Remember this.
One can have up to 10 events, and there can be up to 10 controller points,
but only one pair of controller/controlled. However, add a new event
with the same time points and a new controlled variable.
Example, one second into the run, the throttle shall be mashed and the
vacuum shall go low, then high, and the rpm shall increase. Here are
the events set up in simfile:
event
t 0. 1. 1.2
throttle 5. 5. 85.
end event
event
t 0. 1. 1.2 3.
vacuum 20. 20. 70. 35.
endevent
event
t 0. 1. 3.
rpm 2000. 2000. 4000.
endevent
If you understand the above then you can use events, otherwise you cannot.
ASCII Printouts
EngSim currently has one mode for output - ASCII printout. The amount of
printout is controlled by prinout switches specified in "simfile". The
printout occurs in the file "engsim.out", placed in the same directory
as EngSim.
They are of the form:
print what
where what is one of the following:
inputs - Echo of the pertinent simulation variable at t=t0. This is
good to see if what you actually wanted got interpreted
correctly by EngSim.
global - Prints out the time-related values at a frequency specified
by "prnang" (see above). Simulation time, crank and cam
position, rpm, and rpmdot.
sensor - Output, every prnang crank degrees, the current throttle,
vacuum, and coolant / intake temperatures.
pistonpos - Piston position, all ncyl of 'em, at prnang increments.
pistonvel - Piston velocity (ft/sec), all ncyl, at prnang matches.
pistonacc - Piston acceleration (ft/sec/sec).
pistoncid - Instantaneous swept volume of cylinder (all ncyl) in cubic inches.
cam - Intake and exhaust current valve position (all ncyl) in
inches at the valve.
all - Prints out all of the above at prnang events.
V. Running EngSim
-----------------
Simply type:
engsim
There will be no output to the user's screen. If print options were set, the
file engsim.out is created and filled in.
EngSim is somewhat robust, however it probably has a fair amount of undiscovered
bugs. So if you discover one, let me know (Email: bowling at cebaf.gov) so I
can incorporate a fix.
VI. Obtaining EngSim
-------------------
One can get engsim via. anonymous ftp from the following location
ftp.cebaf.gov/pub/bb/engsim_0.50.tar.Z
Uncompressing and untarring will produce a "c" source, an include file,
this document, and an example simfile.
More information about the Diy_efi
mailing list