Documentation for Simulator

Getting Started

If you have a problem running the code you may need to get a new Java plugin. Microsoft stopped updating their Java years ago and is now transitioning people to Sun's Java.

Sometimes a "refresh" is needed to start the program over clean.


To try out the simulator click on "Design point" and then click on "start simulation". You should see a big round ball that represents the Earth and a line that represents the tether. There will be a dot where the ballast is and also a dot where the center of mass is. There should be text output on the left.

The view is looking down toward the Earth from the North pole. The simulator is only simulating in 2 dimensions (x and y). The 3rd dimension (z) is effectively always zero. This could change someday.

The samples each have some documentation at the top of the input window after you click on them. I recommend playing with them and starting with one that is similar to what you want to do.

More Info

This web page is to help users run the software. Other things you might be interested in are a list of known bugs and limitations, a description of how it models things, and the Java source for the simulator.


To run the simulator you cut/paste some input like that below (or use/modify one of the sample inputs).

I think of the tether as being tapered with a big end and a small end. The ballast is at the big end and the payload at the small end.

So posBigEnd means the starting position of the big end of the tether. All x,y coordinates are relative to the center of the Earth. Positive x is to the right and positive y is up. The on screen view is from the North, so the Earth is rotating counter-clockwise. The velBigEnd means the starting x and y velocities in meters/second.

All distances are in meters and all times in seconds. The tether density is in Kg/meter^2. The tensile is in Gpa or billion Pascals.

Sample input:

posBigEnd   0 7505000
posSmallEnd 0 7000000
restLength    0500000 
velBigEnd     -7400      0  
velSmallEnd   -5400      0 
bigEndDiameter   0.005  
smallEndDiameter 0.003 
density 970          
tensile 3.51
elasticity 0.03      
bigKg       50000  
payloadKg      300      
deltaT           0.01  
timePerDisplay  10    
totalTime     100000  
slices        100     
screenYScaleMeters   16000000  
screenOrigin    Earth    
The restLength and the posBigEnd and posSmallEnd let the program figure out how stretched the tether is to begin with. It is good to watch the tether length at the start of the simulation and see if the length of the tether goes up or down fast - for a good starting position/length it should not.

An alternative to giving posBigEnd and posSmallEnd is to use smallEndHeight to specify a height above the surface of the Earth and also stretch with a number like 1.02 to indicate 2% stretched and it will calculate the positions.

If you use taperType Automatic then you must use smallEndHeight and safetyFactor XX where XX is the safety factor, like 2. In this case you do not need any of stretch, posSmallEnd, posBigEnd, smallEndDiameter, bigEndDiameter. So it is easier to use automatic taper.

The screenOrigin can be "Earth", "EarthTop", "Moon", or a label of an object. If the object is a tether you need to say which part. You can specify a slice number like "T1.4" special names by adding ".Payload", ".CenterOfMass", ".Ballast", or ".C". The ".C" means the position that was the center of mass before the simulation started.

You can scaled how many meters the bottom to top of the screen represents with screenYScaleMeters. To zoom in you just make screenYScaleMeters smaller. You can zoom closer, while still seeing something interesting, when you are centered on something other than Earth.

If you don't want to simulate air rotating with the Earth, you can do rotatingAir false.

The deltaT is how large the time step for each step of the simulation should be. If you make deltaT smaller the simulation takes longer to run, and larger it runs faster. You can run time backwards by making deltaT negative. This can be used to figure out initial conditions to get to some other state. The timePerDisplay is how often to update the display.

The elasticity of 0.03 means that the tether can stretch 3% before breaking. The simulator assumes a theoretical linear spring model over this stretching length.

The slices determines how many slices the tether is simulated as. Note that there will be this many masses and one less than this many springs between the masses. For a more accurate simulation you can increase the slices and decrease the deltaT. Probably play with things where it runs fast, and then when you have something you like do a more accurate/slower simulation.

For a mass you can set massHeight, instead of posMass, and it will calculate a spot directly above the earth that far.

You can set massVelAndAngle vel angle where vel is a number for the velocity in meters per second and angle is a number of degrees above a circular orbit going East. There is also a very similar surfaceVelAndAngle that adds in the rotational speed of the Earth. And a 3rd option is spaceVelAndAngle which is like massVelAndAngle but with normal angles where 0 is to the right and 45 is up and to the right.

You can set massCircularOrbit and it calculates the velocity for a mass at that height. This only works if the mass is directly above the Earth, like when you use massHeight. Have to have already specified the position.

You can set massEccentricity and it calculates the velocity for a mass at that height. This only works if the mass is directly above the Earth, like when you use massHeight. Have to have already specified the position.

The massCd set the mass coefficient of drag. This is used with the massA that sets the effective area for drag calculations.

For the nose/base of the vehicle you can specify a blackBodyArea and the simulator will figure out what temperature it would get to taking into account the heat coming in and black body radiation. By default it uses a formula from page 256 of Hypersonic Aerothermodynamics to calculate how much heat goes into the body. Alternativly you can specify a blackBodyStantonNumber and that fraction of the total heat will be assumed to enter the body. You can also, optionally, specify a blackBodyMass and a blackBodySpecificHeat in which case there will be a heatsink calculation as well as radiation of heat. For a heatsink TPS this is what should be used. blackBodyEmissivity specifies the emissivity and if not included it defaults to 0.9. If you do not specify a blackBodyMass it is as if it were zero mass and has to radiating heat out as fast as it is coming in. This might be used to simulate lightweight ceramic tiles.

We can model sharp body heating, but do not trust this model so much and don't recommend it. The Thermal Protection System, or TPS, can be modeled as well. The tpsThermalConductivity is in Watts/meter-degree where degree is either in kelvin or celsius. The tpsThickness is in meters and is the thickness of the TPS. The tpsArea is the total surface area of the TPS and is in meters squared. The tpsThermalMassFrac is the fraction of the total vehicle mass that can heat up (like vehicle structure and maybe tanks). The tpsSpecificHeat is the Specific Heat of the material that can heat up. The TPS values are only calculated every timePerDisplay so don't make that too large.

To use this you do MakeSharpBody, but it is not recommended. The MakeMass command makes a mass object with the current settings. You can change any number of settings and then make another mass.

For a rocket you can set either the ISP in seconds (really the number of seconds that 1 lb of fuel could give 1 lb of thrust) or the exhaustVelocityMPS which is the exhaust velocity in meters per second. You must also set the pair rocketKg and fuelFraction or the pair dryKg and fuelKg to indicate how much fuel. If you do fuelFraction it just multiplies this by the rocketKg to calculate the fuelKg and (1-fuelFraction) to get dryKg. The rocketKg must be specified before the fuelFraction.

You can specify a ispDegradedAtOneAtm which is a number like 0.12 indicating how much the ISP is degraded at one atmosphere. The simulator will then scale this linearly with the current pressure.

A rocket with a parachute opening can be simulated with rocketParachuteOpenHeight, rocketParachuteArea, rocketParachuteCd. The parachute will not open till the rocket is out of fuel and on the way down. The lift over drag is currently the same after the parachute is open as before.

A rocket can be started later with timeTillIgnite Time where Time is the number of seconds after the simulation has started that the rocket should start firing.

The MakeRocket command makes a rocket object. A rocket finds a payload mass using the "label". If you have more than one rocket for a given mass then they are different stages with the highest stage first.

A rocket can either be rocketStabilizationType fin or rocketStabilizationType spin. It defaults to fin stabilization. In this mode the simulator aligns the thrust of the rocket with whatever the current velocity vector is. So be sure to give your rocket some initial velocity in the direction you want to go, probably with the massVelAndAngle.

In the spin mode you specify something like spinAngle 10.

Also, the thrust is constant. I might put in a G limit someday.

It should be able to do multistage rockets, but this has not been tested just yet. The showXY true command makes the simulator output X and Y components of position and velocity during runs. The default is not to show them.

The showMassToMoon true command shows distance from all masses to the moon. The default is not to show this.

The showEnergy true command shows the potential, kinetic, and total energy of a mass or the ballast of a tether. The default is not to show this.

The showMassToTether command shows the distance from all masses to both ends and the center of mass of a tether. The default is not to show this.

If you want to look at mach effects on the front of the vehicle you need to put in a massNoseAngle. This is the angle from the center line of the vehicle to the width of the cone. This is used in the samples that do reentry. Code seems to fail if Angle is large.

You can do a MakeMoon and the simulator will make a moon that starts out directly above the Earth. At this point the center of the coordinate system is no longer the Earth, but the center of mass of the Earth and Moon together. So the simulator has to simulate the Earth as well.

AtTime can be used to toss a mass from a tether at a certain time. For example:
AtTime 300 toss 1 from T1.Payload to M300 EndAtTime
The 300 is the number of seconds into the simulation to do the toss. the 1 is the number of kilograms to toss. The T1 is the label of the tether we are tossing from. The Payload means the payload end. We can also say Ballast or just a number saying which slice of the tether we want to toss from. The M300 is the label of either an existing mass or a new mass to be created, or it can be nowhere if you just want the mass to go away. The EndAtTime marks the end of the AtTime command.

AtTime can be used to turn on or off logging. For example:
AtTime 500 logXY true EndAtTime. In fact you can do any of the global sets using AtTime. Also, you can do
AtTime 50 stop EndAtTime which will be the same as hitting the stop button while running at that time. So you can resume by clicking on the Go button when you are ready.


If you simulate something and the tether breaks you will see something like "Snap springNum 33". This means that the 33rd slice of the tether, counting from the Ballast broke. Knowing what you set slices to in the input you can figure out how far along the tether this was.

You also see CenMass 6% or some such. This means that the Center of Mass is about 6% of the way down the tether starting at the ballast end. This is only accurate to the resolution of 1 of the slices of the tether even though it has 2 decimal digits. So if you want accuracy for this make lots of slices.

The Earth is spinning as viewed from the North.

The tether has 1 dot at the center of mass and 1 dot at the ballast end.

Along with the position and velocity it also displays the height above the Earth's surface ht and the minimum height and minimum velocities seen so far in the simulation.

There is a tip speed which is the speed of the payload end of the tether relative to the center of mass.

The MaxStretchSpring tells you which slice, counting from the ballast, had the most stretch and what it was. The CurrentMaxStrech is just for the last deltaT.

If you put in a massNoseAngle then the output for that mass will also include the mach number, shock angle, pressure, and temperature on front of vehicle.

Using that atTime with an automatic taper tether and other objects you need to always define the automatic taper tether first.

Depending on the G level, it will either report MGs for mili-Gs or Gs.

If you are simulating a Thermal Protection System (TPS) we output the total amount of heat energy that comes through the TPS in 3 different ways. First we output KW Hours which is the energy in kilo-watt-hours. Next we look at the tpsSpecificHeat and tspThermalMassFrac and calculate how much hotter the inside mass would have gotten from that much heat and report this temperature increase as TempInc which is either celsius or kelvin. And finally we report how many kilograms of water this much heat could boil away to help get a feel for the amount of heat and in case you wanted to use water to keep the frame from getting too hot and report this as BBH2O in Kg. Not that you can scale this to some other ablative. Also note this is not using the steam for transpiration, which would reduce the Kg by something like a factor of 4.

You can do something like AirTest 200000 and it will tell you the density in Kg/meter^3 at that altitude in meters. It will also generate an error and not parse any more input, as this was the easiest way to output this. It was originally just for testing, but it has been handy other times so I decided to document it.

The Sun is to the left. This is important for Solar Sail as it determines which way the photon pressure is coming from, and when it is in shadow. For the EDT this determines when the solar cells have power to thrust. In this model the EDT does not have batteries. If your paragee is toward the Sun then when you pickup a payload your apogee in the shadow drops closer to the Earth. So the reboost is needed on the side toward the sun.

Common Problems


Any questions/feedback encouraged. Email Vincent Cate at The documentation will be updated more if I get the idea people are using the simulator and reading the documentation. :-)
Click for
Copyright (c) 2002, 2003 by Vincent Cate. All rights reserved.