The result of each FIND command is a schedule containing intervals during
which a single geometric constraint is satisfied. FIND commands work for
ephemeris bodies and designated objects alike. (Except for the FIND ORBITAL
LONGITUDE command, which is not defined for designated objects.)
The syntax of every FIND command looks like
FIND @name
< constraint >
(0:1){ WITHIN @schedule }
STEP SIZE @number
The first word is always the word FIND. The second word is always the name of
the output schedule to be created, which is followed by one or more keywords
and values indicating the event or constraint to be found.
Any FIND command may contain the keyword WITHIN followed by the name of an existing schedule, in which case the search is confined to the intervals in this schedule. If no schedule is supplied, the entire default interval is searched. This has the same effect as searching the entire default interval and intersecting it with the specified schedule; but using a search schedule can radically reduce the amount of time required to carry out the search. (Search schedules should be used whenever possible to avoid searching intervals known to be of little interest---for example, searching for satellite events when the primary planet is too close to the Sun for the satellites to be observed anyway.)
The following constraints are supported.
Numeric constraints are relatively straightforward:
< quantity > (1:1){ EQUAL TO \number
| LESS THAN \number
| GREATER THAN \number }
where
< quantity >is the angular rate, apparent diameter, or other quantity associated with a target body.
For example, the command
FIND BIGSEP SEPARATION OF PHOBOS MARS FROM EARTH
GREATER THAN 1 ARCSECOND
STEPSIZE 1 HOUR;
locates intervals when the separation of the limbs of Phobos and Mars is
greater than an arc second.
Minimax constraints are somewhat more complex. The simplest minimax
constraint is the location of the absolute minimum or maximum value of a
quantity across the search schedule:
< quantity > (1:1){ ABSOLUTE MINIMUM
| ABSOLUTE MAXIMUM }
Normally, an absolute extremum is achieved only once within a search schedule
(possibly at an endpoint of one of the intervals), in which case this
constraint locates a single interval of zero length.
For example, the command
FIND schedule FAST
ANGULAR RATE OF FEATURE
FROM OBSERVER ABSOLUTE MINIMUM
STEPSIZE 3 HOURS;
returns the instant (in a zero-length interval) when the angular rate of a
cloud feature is at an absolute minimum.
The next simplest minimax constraint is the location of zero or more local minima or maxima across the search schedule:
< quantity > (1:1){ LOCAL MINIMUM
| LOCAL MAXIMUM }
Local extrema may be achieved any number of times within a search interval.
This constraint always returns intervals of zero length.
For example, the command
FIND FAR
DISTANCE OF MARS FROM EARTH
LOCAL MINIMUM
STEP SIZE 1 DAY;
returns a zero-length interval whenever the distance from Earth to Mars
reaches a local minimum. (Local extrema never occur at the endpoints of the
intervals in the search schedule.)
The most complex minimax constraint is the location of one or more intervals when a quantity is within some tolerance of its absolute minimum or maximum value across the search schedule:
< quantity > (1:1){ ABSOLUTE MINIMUM PLUS \number
| ABSOLUTE MAXIMUM MINUS \number }
For example, the command
FIND WIDE
ELONGATION OF MARS FROM EARTH
ABSOLUTE MAXIMUM MINUS 5 DEGREES
STEP SIZE 1 DAY;
returns intervals when the separation between the Sun and Mars is within 5
degrees of the maximum separation throughout the search schedule---whatever
the maximum separation happens to be.
The default search algorithm is very general, because it is designed to work
for a wide variety of ephemeris and user-defined (designated) objects. As a
result, searches will typically require more time to execute than would be
required by more specialized software, using methods that take into account
some characteristics (periodicity, peculiar orientations, and so on) of a
particular constraint.
Every search currently proceeds with a fixed step size, which you supply with the STEP SIZE clause of the FIND command. The stepsize does not define the resolution to which events are located: they are always located iteratively to the nearest 0.1 seconds. However, the stepsize does affect whether events are found at all. To be safe, you should select the largest stepsize such that the stepsize is still smaller than the expected duration of the event you are looking for.
In the absence of other information, programs search for events during the
entire default interval. However, the search can be confined to the intervals
in an existing schedule with the WITHIN option. The effect is the same as
searching the entire interval and intersecting the resulting schedule with
the search schedule; but it can be orders of magnitude faster.
Because you specify the order in which events are located, you can optimize searches to a great extent.
The graphics subsystem models each defined body as a tri-axial ellipsoid,
with three independent axes. However, most FIND commands model the same
bodies as spheres. In these cases, the sphere has radius equal to the largest
radius of the underlying ellipsoid.
The difference in models means that some events will not be predicted exactly. For instance, at high inclinations, occultations and eclipses may be miscalculated. The magnitude of these errors has not been determined.
During interactive sessions, a FIND command will periodically report its
progress with a little graph like the one shown below.
Search is 37.65 % complete. |************-------------------|
0 100
Some of the FIND commands are redundant. For example, the quadrature of a
body occurs when the elongation is 90 degrees; and elongation is just angular
separation from the Sun. In these cases, the extra commands are provided
because their names are more straightforward.