Ensembles are linked sequences of seismic traces. Ensembles are implemented as objects of class ENSEMBLE; their primary purpose is support for multicomponent seismic data. Similarly to traces, they are practically always accessed using pointers. Ensembles can combine traces of different types and contain no information other than trace ordering. Class ENSEMBLE provides several identifiers and methods for accessing and manipulating their traces:
ENSEMBLE *e;
e->num_traces; // int - the number of traces in the ensemble
e->first_trace; // TRACE* - pointer to the first trace of the ensemble
e->last_trace; // TRACE* - pointer to the last trace of the ensemble
e->next, e->pred; // ENSEMBLE* - pointers to the preceding and next ensembles
// within the same gather
e->sequence; // GATHER* - pointer to the parent trace ensemble gather
e->add_trace(); // add a trace to the end of the ensemble; formatting of the trace
// is controlled by the parent ensemble gather
e->add_first_trace(); // add a trace to the beginning of the ensemble;
// formatting of the trace
// is controlled by the parent ensemble gather
A typical loop scanning traces within an ensemble 'e' looks like this:
for ( TRACE *t = e->first_trace; t; t = t->next )
{
// ...
}
or in reverse order:
for ( TRACE *t = e->last_trace; t; t = t->pred )
{
// ...
}
Two methods deal with the issue of "completeness" of an ensemble, typically meaning the state when the ensemle contains all the records pertaining, for example, to a single surface point. Such completeness is established by the presence of the "last" trace, which is the one having a header named LASTTR set to 1. These two methods are:
e->closed(); // boolean - function that returns TRUE if the last trace in the
// ensemble has the "last trace" flag set
e->close(); // void - sets the "last trace"
Similarly to the traces, new ensembles are usually created by their parent objects, trace gathers:
GATHER *g = SIA_output();
ENSEMBLE *e = g->add_ensemble(); // this adds a trace ensemble to the output gather
Although the call above is possible and may seem appealing, it is not easy to tell from it to which ensemble the trace belongs, what is its sample interval, etc. Such initializations are thus discouraged in application programming.
To delete a trace gracefully (to delete all of its traces, deallocate its memory and to update the parent gather) , use simply:
delete e;
When the last trace in an ensemble is deleted , the ensemble is also removed automatically. Therefore, there is very rarely any need in explicit deletions of ensembles. All ensembles created in the input and output gathers (and that is where you will typically want to create them!) are removed automatically during and after processing.