CALL


overview

  - service calls
  - numeric procedures
  - cell related procedures
  - gas related procedures
  - drift line related procedures
  - signal related procedures
  - histogramming
  - matrix manipulation
  - fitting procedures
  - character string manipulation
  - graphics

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  INQUIRE_FILE          Tells whether a file exists
  INQUIRE_MEMBER        Tells whether a member of a library exists
  INQUIRE_TYPE          Returns the type of a global variables
  PRINT                 Prints its arguments
  TIME_LOGGING          Enters a timing record
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  CARTESIAN_TO_POLAR    Converts Cartesian to polar coordinates
  CARTESIAN_TO_INTERNAL Converts Cartesian to internal coordinates
  POLAR_TO_CARTESIAN    Converts polar to Cartesian coordinates
  POLAR_TO_INTERNAL     Converts polar to internal coordinates
  INTERNAL_TO_CARTESIAN Converts internal to Cartesian coordinates
  INTERNAL_TO_POLAR     Converts internal to polar coordinates
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  GET_CELL_DATA         Returns # of wires, coordinate system etc
  GET_CELL_SIZE         Returns the size of the cell
  GET_PERIODS           Returns the periodicities
  GET_X_PLANE_DATA      Returns the x-plane descriptions
  GET_Y_PLANE_DATA      Returns the y-plane descriptions
  GET_WIRE_DATA         Returns information on a wire
  PLOT_CELL             Plots a cell layout
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  ATTACHMENT            Returns the attachment coeff. for a given E/p
  DRIFT_VELOCITY        Returns the drift velocity for a given E/p
  GAS_AVAILABILITY      Tells which gas description elements are present
  GET_GAS_DATA          Returns pressure, temperature and gas identifier
  GET_E/P_TABLE         Returns the list of E/p values in the table
  ION_MOBILITY          Returns the ion mobility for a given E/p
  LONGITUDINAL_DIFFUSION  Returns sigma_L for a given E/p
  LORENTZ_ANGLES        Returns the Lorentz angle for a given E/p
  TOWNSEND              Returns the Townsend coefficient for a given E/p
  TRANSVERSE_DIFFUSION  Returns sigma_T for a given E/p
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  ELECTRIC_FIELD        Computes the electric field for a given (x,y)
  ELECTRIC_FIELD_3      Computes the electric field for a given (x,y,z)
  FORCE_FIELD           Electrostatic force component (debugging only)
  INTEGRATE_CHARGE      Integrates the charge contained in an area.
  INTEGRATE_FLUX        Integrates the E flux over a parallelogram
  MAGNETIC_FIELD        Computes the magnetic field for a given (x,y)
  MAGNETIC_FIELD_3      Computes the magnetic field for a given (x,y,z)
  MAP_INDEX             Returns a field map index (debugging only)
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  AVALANCHE             Simulates an electron induced avalanche
  DRIFT_ELECTRON        Drifts an electron from a given (x,y)
  DRIFT_ELECTRON_3      Drifts an electron from a given (x,y,z)
  DRIFT_INFORMATION     Returns information about the current drift line.
  DRIFT_ION             Drifts a positive ion from a given (x,y)
  DRIFT_ION_3           Drifts a positive ion from a given (x,y,z)
  DRIFT_MC_ELECTRON     MC drift of an electron from a given (x,y,z)
  DRIFT_MC_ION          MC drift of a positive ion from a given (x,y,z)
  DRIFT_MC_NEGATIVE_ION MC drift of a negative ion from a given (x,y,z)
  DRIFT_NEGATIVE_ION    Drifts a negatvie ion from a given (x,y)
  DRIFT_NEGATIVE_ION_3  Drifts a negative ion from a given (x,y,z)
  GET_CLUSTER           Returns a new cluster position
  GET_DRIFT_LINE        Copies the current drift line to vectors
  NEW_TRACK             Reinitialises the track
  PLOT_DRIFT_AREA       Plots the current drift area
  PLOT_DRIFT_LINE       Plots projections of the current drift line
  PLOT_TRACK            Plots the current track with clusters
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  GET_RAW_SIGNAL        Stores a raw signal in a 1-dimensional matrix
  GET_SIGNAL            Stores a signal in a 1-dimensional matrix
  LIST_RAW_SIGNALS      Lists the raw signals currently in store
  STORE_SIGNAL          Copies a 1-dimensional matrix to a signal
  THRESHOLD_CROSSING    Returns threshold crossings in a signal
  WEIGHTING_FIELD       Computes single electrode ("weighting") fields
  WEIGHTING_FIELD_3     Same as WEIGHTING_FIELD for (x,y,z) coordinates
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  BARYCENTRE            Computes the barycentre of an histogram
  BOOK_HISTOGRAM        Books an histogram
  CONVOLUTE             Convolutes two histograms
  DELETE_HISTOGRAM      Deletes an histogram
  FILL_HISTOGRAM        Fills an histogram
  GET_HISTOGRAM         Retrieves an histogram from a file
  INQUIRE_HISTOGRAM     Returns information about an histogram
  LIST_HISTOGRAMS       Lists the histograms currently in memory
  PLOT_HISTOGRAM        Plots an histogram
  PRINT_HISTOGRAM       Prints an histogram
  WRITE_HISTOGRAM       Writes an histogram to a file
  HISTOGRAM_TO_MATRIX   Copies an histogram to a matrix
  MATRIX_TO_HISTOGRAM   Copies a matrix to an histogram
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  ADJUST_MATRIX         Modifies on or more dimensions of a matrix
  BOOK_MATRIX           Creates a new matrix
  DELETE_MATRIX         Deletes a matrix
  DERIVATIVE            Computes numerically a derivative
  DIMENSIONS            Returns the dimensions of a matrix
  EXTRACT_SUBMATRIX     Returns a sub-matrix of a matrix (internal)
  GET_MATRIX            Retrieves a matrix from a file
  INTERPOLATE           Linear interpolation in an n-dimensional matrix
  INTERPOLATE_i         Local polynomial interpolation in a vector
  LIST_MATRICES         Lists the matrices currently in memory
  MULTIPLY_MATRICES     Multiplies 2 matrices
  PRINT_MATRIX          Prints a matrix
  RESHAPE_MATRIX        Changes the format of a matrix
  SOLVE_EQUATION        Solves a matrix equation
  STORE_SUBMATRIX       Stores a sub-matrix in a matrix (internal)
  WRITE_MATRIX          Writes a matrix to a file
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  FIT_EXPONENTIAL       Fits a exponential to an histogram or to vectors
  FIT_FUNCTION          Fits an arbitrary function
  FIT_GAUSSIAN          Fits a Gaussian to an histogram or to vectors
  FIT_MATHIESON         Fits a Mathieson distribution to an histogram
  FIT_POLYA             Fits a Polya distribution
  FIT_POLYNOMIAL        Fits a polynomial to an histogram or to vectors
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  STRING_DELETE         Deletes a portion from a string
  STRING_INDEX          Returns the start position of a sub-string
  STRING_LENGTH         Returns the length of a string
  STRING_LOWER          Converts a string to lower case
  STRING_MATCH          Tells whether 2 strings match
  STRING_PORTION        Returns a sub-string
  STRING_UPPER          Converts a string to upper case
  STRING_WORDS          Counts the number of words in a string
  STRING_WORD           Returns a selected word from a string
  ----------------------------------------------------------------------

  ----------------------------------------------------------------------
  Procedure name        Purpose
  ----------------------------------------------------------------------
  PLOT_AREA             Plots a fill-area
  PLOT_COMMENT          Places a comment on the current plot
  PLOT_CONTOURS         Plots 2-matrix as a set of contours
  PLOT_END              Closes the current plot
  PLOT_ERROR_BAND       Plots an error band
  PLOT_ERROR_BAR        Plots a series of error bars
  PLOT_FRAME            Plots a set of coordinate axes
  PLOT_GRAPH            Plots a graph
  PLOT_LINE             Plots a line
  PLOT_MARKER           Plots a series of markers
  PLOT_SURFACE          Plots 2-matrix as a 3-dimensional surface plot
  PLOT_TEXT             Plots a text string
  PROJECT_LINE          Projects a line
  PROJECT_MARKERS       Projects a set of markers
  ----------------------------------------------------------------------

ADJUST_MATRIX

  ADJUST_MATRIX is one of two procedures that modify the
  shape of an existing matrix. ADJUST_MATRIX is designed
  to modify the size of a matrix in one or more dimensions,
  without however changing the place the elements occupy.

  ADJUST_MATRIX operates by creating a new matrix of the
  requested dimensions, then copying the elements from
  the old matrix to the same place in the new matrix. If
  the new matrix is smaller in any dimension, some elements
  are lost, even if the overall size of the matrix is larger.
  If a dimension of the new matrix is larger than the
  corresponding dimension of the old matrix, then the new
  elements are filled with PAD (the last argument).

  ADJUST_MATRIX can not be used to change the number of
  dimensions that a matrix has.

  Format:

  CALL ADJUST_MATRIX(matrix, size_1, size_2, ... size_n, pad)

  Example:

  Global n=3
  Call book_matrix(a,2,n)
  For i From 1 To 2 Do
     Say "How many elements to initialise in row {i} ?"
     Global n_new=n
     Parse terminal n_new
     If n_new>n Then
        Call adjust_matrix(a,2,n_new,pi)
        Global n=n_new
     Endif
     For j From 1 To n Do
        Global a[i;j]=i*j
     Enddo
  Enddo
  Call print_matrix(a)

  A matrix is initially booked as 2x3, but since the amount
  of data to be stored in the matrix is not a priori known,
  the matrix may have to be extended. This is the approach
  followed by the READ-VECTORS command. The PAD argument is
  compulsory in ADJUST_MATRIX, and is likely to be used in
  this example.

ATTACHMENT

  Returns the attachment coefficient, if available, for a given
  value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

  If the field is specified with vectors, then the result will
  also be a vector. Otherwise the result will be a scalar. It
  is permitted to specify 1 or 2 components of the field with
  scalars and the other(s) with vectors. The result will still
  be a vector in that case.

  The electric field should be in V/cm, the attachment coefficient
  is returned in 1/cm.

  Format:

  CALL ATTACHMENT(ex, ey, ez, attachment)

AVALANCHE

  Simulates an electron induced avalanche, taking diffusion,
  multiplication and attachment into account.

  An initial electron is drifted, at your choice, using either the
  Monte Carlo technique or using Runge Kutta Fehlberg integration.
  When using the Monte Carlo method, care has to be taken that the
  step size is set properly (see INTEGRATION-PARAMETERS). Runge
  Kutta Fehlberg integration is faster because diffusion is not
  taken into account, as a result of which far fewer drift lines
  have to be computed.

  At each step, a number of secondary electron and ions is drawn
  according to the local Townsend and attachment coefficients.
  Newly produced electrons are traced like the initial one. The
  ions are drifted and their end point is recorded.

  This procedure can produce a graphical representation of
  the avalanche, and can also return statistical information.

  Format:

  CALL AVALANCHE(x, y, z, option, n_electron, n_ion, ...
     formula_1, histogram_1, formula_2, histogram_2 ...)

  Example:

  &DRIFT
  area -0.02 -0.02 0.02 0.02
  int-par m-c-dist-int 0.0002
  Call book_histogram(elec,50,0,2500)
  Call book_histogram(ion,50,0,2500)
  Call book_histogram(created,50,-0.02,+0.02)
  Call book_histogram(lost,50,-0.02,+0.02)
  Call book_histogram(end_e,50,-0.02,+0.02)
  Call book_histogram(end_ion,50,-0.02,+0.02)
  For i From 1 To 100 Do
     Call plot_drift_area
     Call avalanche(0.010,0.019,0,`plot-electron,plot-ion`,ne,ni,...
        `y_created`,created,`y_lost`,lost,`y_e`,end_e,`y_ion`,end_ion)
     Say "Electrons: {ne}, ions: {ni} (avalanche {i})"
     Call fill_histogram(elec,ne)
     Call fill_histogram(ion,ni)
     Call plot_end
  Enddo
  Call fit_exponential(elec,a,b,ea,eb,`plot`)
  Say "Slope: {-1/b}"
  !opt log-y
  Call hplot(elec,`Electrons`,`Number of electrons after avalanche`)
  Call hplot(ion,`Ions`,`Number of ions produced in avalanche`)
  Call hplot(created,`y [cm]`,`Production point of electrons`)
  Call hplot(lost,`y [cm]`,`Absorption point of electrons`)
  Call hplot(end_e,`y [cm]`,`End point of electrons`)
  Call hplot(end_ion,`y [cm]`,`End point of ions`)

  After setting the AREA, the parameters for Monte Carlo drift
  line integration are set such that there are about 100 steps
  on each drift line. The output histograms are booked beforehand
  so as to ensure they have a common scale. Then, 100 avalanches
  are produced, all of which are fully plotted, after which the
  overview statistics are shown.

Additional Information on:

  • option
  • n_electron
  • n_ion
  • formula
  • histogram

  • BARYCENTRE

      Returns the barycentre of the area around the highest peak
      in the histogram.
    
      The procedure works by sliding a window of width NBIN over
      the histogram to locate a maximum (if several peaks have
      the same maximum, then the first peak is taken). Then, the
      weighted mean of the entries within the window is computed
      and returned.
    
      If the calculation fails (no maximum), then the global
      variable OK will be set to False, otherwise to True.
    
      Format:
    
      CALL BARYCENTRE(histogram, barycentre [, nbin])
    

    Additional Information on:

  • histogram
  • barycentre
  • nbin

  • BOOK_HISTOGRAM

      The BOOK_HISTOGRAM books a new histogram.
    
      Only the histogram reference is mandatory, all other
      arguments are optional.
    
      Format:
    
      CALL BOOK_HISTOGRAM(reference, [number of bins, ...
           [minimum, maximum]] [, options]])
    
      Example:
    
      Call book_histogram(ref,10,2,3)
      Call book_histogram(ref,10,`integer`)
    
      The first example books an histogram of 10 bins for the range
      [2,3]. The second example books an histogram with 10 bins each
      spanning an integer range with an automatically chosen scale.
    
      See also FILL_HISTOGRAM.
    

    Additional Information on:

  • reference
  • bins
  • range
  • options

  • BOOK_MATRIX

      Creates a matrix of specified dimensions, to be associated
      with a global variable.
    
      If the global variable is already in use, anything attached
      to it at the moment BOOK_MATRIX is called will be deleted.
      In particular, if the global variable is already a matrix,
      then the matrix is first deleted before a newly created
      matrix is associated with the global variable.
    
      Format:
    
      CALL BOOK_MATRIX(global, size_1, size_2, ...)
    
      Example:
    
      Call book_matrix(cube,3,3,3)
    
      Books a 3x3x3 matrix which can be accessed via the global
      variable CUBE.
    

    CARTESIAN_TO_INTERNAL

      Applies the conformal mapping of Cartesian (x,y) coordinates to
      internal (rho,phi) coordinates. The (rho,phi) coordinates are
      used internally in the program when the cell is described in
      polar coordinates. The internal coordinates are defined by:
    
           rho = 0.5*log(x**2+y**2)     [dimension not defined]
           phi = arctan(y/x)            [phi in radians]
    
      The input arguments of this procedure can be either of type Number
      or of type Matrix. If the input type is Matrix, then the two input
      matrices must have the same total number of elements. The output
      matrices will have the same structure as the first input matrix.
    
      The abbreviated procedure name CTR is also accepted.
    
      Format:
    
      CALL CARTESIAN_TO_INTERNAL(x,y,rho,phi)
    

    CARTESIAN_TO_POLAR

      Converts Cartesian (x,y) coordinates to polar (r,phi) coordinates.
      The angle phi is in degrees.
    
      The input arguments of this procedure can be either of type Number
      or of type Matrix. If the input type is Matrix, then the two input
      matrices must have the same total number of elements. The output
      matrices will have the same structure as the first input matrix.
    
      The abbreviated procedure name CTP is also accepted.
    
      Format:
    
      CALL CARTESIAN_TO_POLAR(x,y,r,phi)
    

    CONVOLUTE

      Computes the convolution of 2 histograms (ref1 and ref2) and
      stores the result (ref3) in a new histogram. The 2 input
      histograms must have the same bin width.
    
      The range of the output histogram is chosen as the combined
      range of the two input histograms. The bin width of the output
      histogram is the same as the bin width of the input histograms.
    
      If the calculation fails (different bin widths, not enough
      memory), then the global variable OK will be set to False,
      otherwise to True.
    
      Format:
    
      CALL CONVOLUTE(ref1, ref2, ref3)
    

    DELETE_HISTOGRAM

      Deletes a histogram. The memory associated with the histogram is
      only released at the next histogram garbage collect, usually only
      carried out when there are no free histogram slots left.
    
      If the histogram was known via a global variable, as is usually
      the case, then the global variable will still exist after this call.
      However, the type of such a global variable changes to Undefined.
    
      Format:
    
      CALL DELETE_HISTOGRAM(reference)
    

    Additional Information on:

  • reference

  • DELETE_MATRIX

      The DELETE_MATRIX procedure frees the memory occupied by
      matrices and returns the associated global variables to
      type Undefined.
    
      If a DELETE_MATRIX call is issued without arguments, then
      all existing matrices are deleted, whether associated with
      a global variable or not.
    
      Format:
    
      CALL DELETE_MATRIX(matrix_1, matrix_2, ...)
    
      Example:
    
      Call book_matrix(a,2,3,4,5)
      Call delete_matrix(a)
    

    DERIVATIVE

      Computes an approximation of the derivative y'(x) at x_int
      where x and y are given as matrices and where x_int is a
      number.
    
      The calculation is using an interpolation between y and x
      of an order that can be specified with the OPTION argument,
      and which is by default 2.
    
      Format:
    
      CALL DERIVATIVE(x, y, x_int, dy [, option])
    
      Example:
    
      Read-vector x
      -3,-2.3,-1,0,1,2,5,7,8,12
    
      Global y=x**2
      Say "Please enter a value"
      Parse terminal xint
      Call derivative(x,y,xint,dy)
      Say "Derivative: {dy} should be {2*xint}."
    
      This example verifies that the derivative is approximately
      correct. If y had been set to x**3, the derivative would be
      inaccurate unless one adds the option `cubic`.
    

    Additional Information on:

  • x
  • y
  • x_int
  • dy
  • option

  • DIMENSIONS

      Returns the number of dimensions (n_dimensions) of the matrix
      and a vector with the size of the matrix in each of the
      dimensions.
    
      Format:
    
      CALL DIMENSIONS(matrix, n_dimensions, dimension_vector)
    
      Example:
    
      Call get_matrix(abc,`abc.mat`)
      Call dimensions(abc,n_dim,dim_abc)
      Global nx=number(dim_abc[1])
      Global ny=number(dim_abc[2])
      Say "Matrix abc has {n_dim} dimensions, shape is {nx}x{ny}x..."
      Call delete_matrix(dim_abc)
    
      A matrix is read from a file, and the example shows how one
      can find out what the dimensions of the object are. The
      'number' function is used to convert the 1-matrices dim_abc[1]
      and dim_abc[2] into numbers - this is purely esthetic since
      Say would place parentheses around the values of nx and ny.
    

    DRIFT_ELECTRON

      Calculates a electron drift line from the point (x, y) and
      returns the drift time, the status (hit a wire, left the
      area etc) and optionally also the integrated diffusion, the
      multiplication and the losses through attachment.
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      The integrated diffusion, the multiplication and the attachment
      losses can only be computed if resp. longitudinal diffusion,
      Townsend and attachment data have been supplied in the &GAS
      section. The integrated diffusion takes the transverse diffusion
      into account if both transverse and longitudinal diffusion
      coefficients have been entered.
    
      Format:
    
      CALL DRIFT_ELECTRON(x, y, status, time [,diffusion ...
           [, multiplication [,attachment]]])
    

    Additional Information on:

  • status

  • DRIFT_ELECTRON_3

      Calculates a electron drift line from the point (x, y, z) and
      returns the drift time, the status (hit a wire, left the
      area etc) and optionally also the integrated diffusion, the
      multiplication and the losses through attachment.
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      The integrated diffusion, the multiplication and the attachment
      losses can only be computed if resp. longitudinal diffusion,
      Townsend and attachment data have been supplied in the &GAS
      section. The integrated diffusion takes the transverse diffusion
      into account if both transverse and longitudinal diffusion
      coefficients have been entered.
    
      Format:
    
      CALL DRIFT_ELECTRON_3(x, y, z, status, time [,diffusion ...
           [, multiplication [,attachment]]])
    

    Additional Information on:

  • status

  • DRIFT_ION

      Calculates a drift line for a positively charged ion from the point
      (x, y) and returns the drift time and the status (hit a wire, left
      the area etc).
    
      The integrated diffusion, the multiplication and the attachment
      losses are not computed.
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      Format:
    
      CALL DRIFT_ION(x, y, status, time)
    

    Additional Information on:

  • status

  • DRIFT_ION_3

      Calculates a drift line for a positively charged ion from the point
      (x, y, z) and returns the drift time and the status (hit a wire,
      left the area etc).
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      The integrated diffusion, the multiplication and the attachment
      losses are not computed.
    
      Format:
    
      CALL DRIFT_ION_3(x, y, z, status, time)
    

    Additional Information on:

  • status

  • DRIFT_MC_ELECTRON

      Performs a Monte-Carlo calculation of an electron drift line, taking
      diffusion into account on a step-by-step basis. The drift line starts
      from the point (x,y,z). The procedure returns the drift time, the status
      (hit a wire, left the area etc) and optionally also the multiplication
      and the losses through attachment.
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      This procedure can only meaningfully be used if both the transverse and
      the longitudinal diffusion have been supplied in the &GAS section. The
      multiplication and the attachment losses can only be computed if Townsend
      and attachment data have been entered.
    
      Format:
    
      CALL DRIFT_MC_ELECTRON(x, y, z, status, time ...
           [, multiplication [,attachment]])
    

    Additional Information on:

  • status

  • DRIFT_MC_ION

      Performs a Monte-Carlo calculation of a drift line for a positively
      charged ion, taking diffusion into account on a step-by-step basis.
      The drift line starts from the point (x,y,z). The procedure returns
      the drift time and the status (hit a wire, left the area etc).
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      It should be noted that MC drift of electrons and ions uses the same
      set of integration parameters (step size in particular). Care should
      be taken to set these parameters to reasonable values for ions before
      this procedure is called.
    
      Diffusion coefficients for ions can be set with the PARAMETERS
      statement in the gas section.
    
      Multiplication and attachment losses are not evaluated.
    
      Format:
    
      CALL DRIFT_MC_ION(x, y, z, status, time)
    

    Additional Information on:

  • status

  • DRIFT_MC_NEGATIVE_ION

      Performs a Monte-Carlo calculation of a drift line for a negatively
      charged ion, taking diffusion into account on a step-by-step basis.
      The drift line starts from the point (x,y,z). The procedure returns
      the drift time and the status (hit a wire, left the area etc).
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      It should be noted that MC drift of electrons and ions uses the same
      set of integration parameters (step size in particular). Care should
      be taken to set these parameters to reasonable values for ions before
      this procedure is called.
    
      Diffusion coefficients for ions can be set with the PARAMETERS
      statement in the gas section.
    
      Multiplication and attachment losses are not evaluated.
    
      Format:
    
      CALL DRIFT_MC_NEGATIVE_ION(x, y, z, status, time)
    

    Additional Information on:

  • status

  • DRIFT_NEGATIVE_ION

      Calculates a drift line for a negatively charged ion from the
      point (x, y) and returns the drift time and the status (hit a
      wire, left the area etc).
    
      The integrated diffusion, the multiplication and the losses
      through attachment are not computed.
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      Format:
    
      CALL DRIFT_NEGATIVE_ION(x, y, status, time)
    

    Additional Information on:

  • status

  • DRIFT_NEGATIVE_ION_3

      Calculates a drift line for a negatively charged from the point
      (x, y, z) and returns the drift time and the status (hit a wire,
      left the area etc).
    
      This procedure should be called only from within the drift or
      signal sections, after the cell and the gas have been entered.
    
      The integrated diffusion, the multiplication and the losses
      through attachment are not computed.
    
      Format:
    
      CALL DRIFT_NEGATIVE_ION_3(x, y, z, status, time)
    

    Additional Information on:

  • status

  • DRIFT_INFORMATION

      Returns the various pieces of information about the current
      drift line, such as the number of steps and the numeric status
      code.
    
      This procedure can be called after any of the drift line
      computation procedures has been called (DRIFT_ELECTRON,
      DRIFT_ELECTRON_3, DRIFT_ION etc).
    
      Format:
    
      CALL DRIFT_INFORMATION( ...
           {`CHARGE`, q | ...
            `DRIFT-TIME`, time | ...
            `PARTICLE`, particle | ...
            `STATUS-CODE`, istat | ...
            `STATUS-STRING`, status | ...
            `STEPS`, nsteps}
    
      Example:
    
      Call plot_drift_area
      Call drift_electron_3(2.5,3.5,4.5,status,time)
      Call plot_drift_line
      Call plot_end
      Say "Status: {status}"
      Call string_index(status,`wire`,index1)
      Call string_index(status,`replica`,index2)
      If 'index1>0 & index2=0' Then
         Call drift_information('status-code',wire)
         Say "The particle hit wire {wire}."
      Endif
    
      An electron drift line is computed. The DRIFT_ELECTRON_3 procedure
      returns a formatted status string which, if the electron hits a
      wire, has the format "Hit an X wire" or "Hit an X wire replica". The
      STRING_INDEX procedure searches for the strings "wire" and "replica"
      to determine whether an original copy of a wire has been hit. If
      this is the case, the DRIFT_INFORMATION procedure is called to find
      the number of the wire that has been hit.
    

    Additional Information on:

  • q
  • time
  • particle
  • istat
  • status
  • nsteps

  • DRIFT_VELOCITY

      Returns the drift velocity, if available, for a given value
      of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).
    
      If the field is specified with vectors, then the result will
      also be a vector. Otherwise the result will be a scalar. It
      is permitted to specify 1 or 2 components of the field with
      scalars and the other(s) with vectors. The result will still
      be a vector in that case.
    
      The electric field should be in V/cm, the drift velocity is
      returned in cm/microsec.
    
      Format:
    
      CALL DRIFT_VELOCITY(ex, ey, ez, drift)
    

    ELECTRIC_FIELD

      Returns the electric field vector and the potential at
      a given point.
    
      The arguments ex, ey, ez, e, v and status are optional.
    
      Format:
    
      CALL ELECTRIC_FIELD(x, y, ex, ey, ez, e, v, status)
    
      Example:
    
      &CELL
      plane x=-1
      plane y=-1
      rows
      s * * 1 1 1000
    
      &FIELD
      Global n=6
      Call book_matrix(x,n,n)
      Call book_matrix(y,n,n)
      For i From 1 To n Do
         For j From 1 To n Do
            Global x[i;j]=(i-1)/(n-1)
            Global y[i;j]=(j-1)/(n-1)
         Enddo
      Enddo
      Call efield(x,y,ex,ey,ez,e,v,stat)
      Call print_matrix(x,y,ex,ey,ez,e,v,stat)
      area 0 0 1 1
      grid {n}
      print ex ey e v
    
      In a simple chamber, one uses on the one hand the ELECTRIC_FIELD
      procedure to compute the field on a 6x6 grid, on the other hand
      the PRINT command is used to verify the result.
    

    Additional Information on:

  • coordinates
  • field
  • status

  • ELECTRIC_FIELD_3

      Returns the electric field vector and the potential at
      a given point. This routine is to be used in case the
      field has structure along the z-axis, for instance because
      of the presence of space charge.
    
      The arguments ex, ey, ez, e, v and status are optional.
    
      Format:
    
      CALL ELECTRIC_FIELD_3(x, y, z, ex, ey, ez, e, v, status)
    
      Example:
    
      See ELECTRIC_FIELD.
    

    Additional Information on:

  • coordinates
  • field
  • status

  • EXTRACT_SUBMATRIX

      Extracts a submatrix from a (larger) matrix.
    
      The matrix from which elements are to be extracted should exist
      prior to the call, the receiving matrix should not exist prior
      to the call.
    
      This procedure is used to process array indexing on the right
      hand side of formulae, in procedure calls etc. This procedure
      is not meant to called by the user. It is much simpler to get
      sub-matrices using indexing expressions.
    
      Format:
    
      CALL EXTRACT_SUBMATRIX(ndim, nsel_1, nsel_2, ... , ...
           isel_1_1, isel_1_2, ..., isel_2_1, isel_2_2, ... , ...
           isel_n_1, isel_n_2, ref_submatrix, ref_matrix)
    

    FILL_HISTOGRAM

      This procedure adds an entry to an existing histogram.
    
      Format:
    
      CALL FILL_HISTOGRAM(reference, entry [, weight])
    
      Example:
    
      Call book_histogram(ref,100)
      For i From 1 To 10000 Do
         Call fill_histogram(ref,rnd_landau)
      Enddo
      Call plot_histogram(ref,"Energy loss","Landau distribution")
    
      This example could be used to check that the Landau random
      number generator does indeed work.
    

    Additional Information on:

  • reference
  • entry
  • weight

  • FIT_EXPONENTIAL

      Fits an exponential of a polynomial to an histogram or to
      1-dimensional matrices.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True is the fit converged, and False
      otherwise.
    
      Format for histograms:
    
      CALL FIT_EXPONENTIAL(reference, a0, a1, a2, ..., an, ...
           err_a0, err_a1, err_a2, ..., err_an [, options])
    
      Format for matrices:
    
      CALL FIT_EXPONENTIAL(x, y, err_y, a0, a1, a2, ..., an, ...
           err_a0, err_a1, err_a2, ..., err_an [, options])
    
      Example:
    
      &SIGNAL
      aval polya-town 0.5
      check avalanche from 0 0.5 range 0.1 10000 keep-histograms
      Call fit_exponential(avalanche,a0,a1,ea0,ea1,`print,plot`)
      Say "a0 = {a0}+/-{ea0}, a1 = {a1}+/-{ea1}."
    
      In this example, the user wishes to see how well a Polya
      distribution with parameter theta=0.5, can be reproduced
      by an exponential.
    

    Additional Information on:

  • reference
  • x
  • y
  • err_y
  • a
  • err_a
  • options

  • FIT_FUNCTION

      Fits an arbitrary function to an histogram or to 1-dimensional
      matrices. Fitting a Landau distribution to an histogram, seems
      to be a common application of this procedure.
    
      This procedure, unlike the other fitting procedures, does not
      try to find suitable starting values for the fitting parameters.
      A starting value for each parameter must therefore be supplied
      by the user.
    
      Since this procedure uses the symbolic evaluation procedures of
      Garfield, the fit works essentially in single precision. In order
      to have a chance to be successful, the problem must therefore be
      well conditioned.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True is the fit converged, and False
      otherwise.
    
      Format for histograms:
    
      CALL FIT_FUNCTION(reference, function, ...
           par1, par2, par3, ... , err1, err2, err3, ... [, options])
    
      Format for matrices:
    
      CALL FIT_FUNCTION(x, y, err_y, function, ...
           par1, par2, par3, ... , err1, err2, err3, ... [, options])
    
      Example:
    
      Call book_histogram(ref,50,-1,3)
      For i From 1 To 500 Do
         Global x=-1+4*rnd_uniform
         Global w=x**2+1
         Call fill_histogram(ref,x,w)
      Enddo
      Global c=100
      Global a=2
      Global b=1
      Call fit_function(ref,`c+a*(1+b*x**2)`,a,b,ea,eb,`plot,print`)
      Say "Function: {c}+{a}*(1+{b}*x**2), errors {ea,eb}"
      Say "{a+c} +/- {abs(ea)} should be equal to"
      Say "{a*b} +/- {a*b*sqrt((ea/a)**2+(eb/b)**2)}"
    
      (This is a simple test of the FIT_FUNCTION procedure in
      which the function depends on 3 global variables A, B and C
      of which A and B are varied while C is kept fixed.)
    

    Additional Information on:

  • function
  • reference
  • x
  • y
  • err_y
  • parameters
  • errors
  • options

  • FIT_GAUSSIAN

      Fits a Gaussian to a set of 1-dimensional matrices or
      to an histogram.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True is the fit converged, and False
      otherwise.
    
      Format for histograms:
    
      CALL FIT_GAUSSIAN(reference, integral, mean, sigma ...
           [, err_int [, err_mean [, err_sigma [, options]]]])
    
      Format for matrices:
    
      CALL FIT_GAUSSIAN(x, y, err_y, integral, integral, mean, sigma ...
           [, err_int [, err_mean [, err_sigma [, options]]]])
    
      Example 1:
    
      Call get_histogram(sel_5,`arrival.hist`,`sel_5`)
      Call fit_gaussian(sel_5,dum,dum,sigma,dum,dum,esigma,`PLOT`)
      Say "Gaussian width is {sigma} +/- {esigma}."
    
      (The ARRIVAL instruction only returns the RMS of the arrival
      time distributions. To obtain Gaussian fits in addition, you
      should specify the KEEP-HISTOGRAMS option and then use the
      last two of the calls shown above. The GET_HISTOGRAM call is
      used if you first save the histograms in a file and  then fit
      the histograms in a separate job.)
    
      Example 2:
    
      Call book_histogram(hist)
      For i From 1 To 10000 Do
         Global sum=0
         For j From 1 To 12 Do
            Global sum=sum+rnd_uniform
         Enddo
         Call fill_histogram(hist,sum)
      Enddo
      Call fit_gaussian(hist,a,b,c,ea,eb,ec,`print,plot`)
    
      (This verifies the approximation of a Gaussian distribution
      by the sum of 12 uniformly distributed random numbers.)
    

    Additional Information on:

  • reference
  • x
  • y
  • err_y
  • integral
  • mean
  • sigma
  • errors
  • options

  • FIT_MATHIESON

      Fits a integrated Mathieson distribution to an histogram. This
      distribution is intended to describe the signal induced in a
      cathode plane that is segmented into strips.
    
      The Mathieson distribution depends on a shape parameter, called
      K3, which is a function of the geometrical structure of the
      chamber, and on the ratio of strip width and anode-cathode
      distance. The distribution assumes that the avalanche is localised
      on anode wires placed centrally with respect to the cathode strips.
    
      The procedure derives the strip width from the bin width of the
      input histogram, the anode-cathode distance has to be entered as
      an argument. The K3 parameter can be fitted, but may optionally
      also be kept constant during the fit at a user-specified value.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True is the fit converged, and False
      otherwise.
    
      Format:
    
      CALL FIT_MATHIESON(reference, distance, norm, centre, k3, ...
           err_norm, err_centre, err_k3, [, options])
    
      Example:
    
      Call book_histogram(ref_m,50)
      Call book_histogram(ref_b,50)
      For i From 1 To 65 Do
         Call get_histogram(hist,`profile.hist`,string(i))
         Global k3=0.1
         Global s=0.254
         Call fit_mathieson(hist,s,f,xc,k3,ef,exc,ek3,...
            `noplot,noprint,equal,fitk3`)
         Call fill_histogram(ref_m,xc)
         Call barycentre(hist,b,5)
         Call fill_histogram(ref_b,b)
         Say "Center:     {xc} +/- {exc}"
         Say "Barycenter: {b}"
         Say "K3:         {k3} +/- {ek3}"
      Enddo
      Call plot_histogram(ref_m,`Reconstructed x [cm]`,`Mathieson fits`)
      Call plot_histogram(ref_b,`Reconstructed x [cm]`,`Barycenter`)
    
      (We have already produced a file that contains for 65 events
      a distribution of induced charges in the pads, and now we fit
      each of these with a Mathieson distribution and compare these
      fits with barycentres. The K3 parameter is left free.)
    
      References:
    
      E Mathieson & JS Gordon, NIM 227 (1984) 267-276
      JS Gordon & E Mathieson, NIM 227 (1984) 277-282
      E Mathieson, NIM A270 (1988) 602-603
    

    Additional Information on:

  • distance
  • centre
  • norm
  • k3
  • errors
  • options

  • FIT_POLYA

      Fits a Polya distribution to an histogram or to 1-dimensional
      matrices. The Polya distribution is a special case of a gamma
      distribution and is sometimes used, as a semi-empiric formula,
      to describe avalanche fluctuations around wires.
    
      This procedure optionally tries to determine the a linear horizontal
      scale correction for which the fit is optimal. But, fitting a Polya
      distribution with a free scale is a numerically poorly conditioned
      problem because of the high correlation between the Polya parameter
      and the scale parameters. If the scale is known, then it is preferable
      to fix the scale.
    
      Similarly, the routine will make an attempt to estimate the Polya
      parameter if no starting value is known, but it is better to provide
      a starting value if one is known with reasonable accuracy.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True is the fit converged, and False
      otherwise.
    
      Format for histograms:
    
      CALL FIT_POLYA(reference, factor, offset, slope, theta, ...
           err_factor, err_offset, err_slope, err_theta [, options])
    
      Format for matrices:
    
      CALL FIT_POLYA(x, y, err_y, factor, offset, slope, theta, ...
           err_factor, err_offset, err_slope, err_theta [, options])
    
      Example:
    
      Call book_histogram(ref,100,0,10)
      For i From 1 To 2000 Do
         Call fill_histogram(ref,1+2*rnd_polya(1))
      Enddo
      Global o=-1/2
      Global s=1/2
      Global t=500
      Global f=200
      Call fit_polya(ref,f,o,s,t,ef,eo,es,et,`plot,print,poisson,auto`)
      Say "Scaling X={o}+{s}*x, theta={t}+/-{et}, contents={f}."
    
      (First we fill a histogram with a Polya distribution of which we
      know the theta parameter and the scale, then we check whether the
      fit finds the input values back. We don't need to give initial
      values in this case since the AUTO option is specified.)
    

    Additional Information on:

  • reference
  • x
  • y
  • err_y
  • parameters
  • errors
  • options

  • FIT_POLYNOMIAL

      Fits a polynomial to an histogram or to 1-dimensional matrices.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True is the fit converged, and False
      otherwise.
    
      Format for histograms:
    
      CALL FIT_POLYNOMIAL(reference, a0, a1, a2, ..., an, ...
           err_a0, err_a1, err_a2, ..., err_an [, options])
    
      Format for matrices:
    
      CALL FIT_POLYNOMIAL(x, y, err_y, a0, a1, a2, ..., an, ...
           err_a0, err_a1, err_a2, ..., err_an [, options])
    
      Example:
    
      Call hdelete(ref)
      Call hbook(ref,100,-2,2)
      For i From 1 To 10000 Do
         Global x=(rnd_uniform-0.5)*4
         Global dy=0.01*(rnd_uniform-0.5)
         Call hfill(ref,x,1+2*x+x**2+dy)
      Enddo
      Call fit_polynomial(ref,a0,a1,a2,ea0,ea1,ea2,`print,plot`)
      Say "a0 = {a0}+/-{ea0}, a1 = {a1}+/-{ea1}, a2 = {a2}+/-{ea2}."
    
      This example is a test to verify that the fit works.
    

    Additional Information on:

  • reference
  • x
  • y
  • err_y
  • a
  • err_a
  • options

  • FORCE_FIELD

      Returns the electrostatic component of the force experienced by
      a wire that would have been located at the specified position.
      The field still has to be multiplied by a charge to get a force.
    
      This procedure is only of use for debugging, and must be used
      with caution since it is on purpose not protected for locations
      inside wires (the call can result in a division by zero).
    
      Format:
    
      CALL FORCE_FIELD(x, y, ex, ey)
    

    Additional Information on:

  • coordinates
  • field

  • GAS_AVAILABILITY

      Returns the status of the gas data.
    
      Format:
    
      CALL GAS_AVAILABILITY(object, available)
    

    Additional Information on:

  • object
  • available

  • GET_CELL_DATA

      Informs about the number of wires in the cell, the potential
      function used to compute the fields and the coordinate system
      in which the cell has been described. The procedure also
      returns the cell indentifier.
    
      All arguments are optional.
    
      Format:
    
      CALL GET_CELL_DATA([number of wires [, cell type [, ...
           coordinates [, identifier]]]])
    

    GET_CELL_SIZE

      Returns the dimensions of the cell.
    
      If the cell has been entered in polar coordinates, then the
      dimensions are returned in internal coordinates. These can
      be converted to Cartesian or polar coordinates with the
      INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.
    
      If 4 arguments are provided, only the (x,y) part of the cell
      dimensions is returned. If 6 arguments are present, also the
      z part is set.
    
      Formats:
    
      CALL GET_CELL_SIZE(xmin, ymin, zmin, xmax, ymax, zmax)
      CALL GET_CELL_SIZE(xmin, ymin, xmax, ymax)
    
      Example: see GET_WIRE_DATA
    

    GET_CLUSTER

      Once cluster generation has been initialised by means of a
      call to NEW_TRACK, one can repeatedly call GET_CLUSTER to
      get one cluster at the time.
    
      In addition to the parameters, the global variable OK is set by
      this procedure. Its value is True if generating the clusters
      worked properly, otherwise it will be set to False. Note that
      OK is also set to False if DONE has been set to True.
    
      Before using the cluster location and energy, the value of DONE
      and OK should be checked. The parameters should not be used if
      either of these two has been set to True.
    
      The cluster location is returned in Cartesian coordinates
      also if the cell has been entered in polar coordinates.
    
      Format:
    
      CALL GET_CLUSTER(xcls, ycls, zcls, npair, ecls, done)
    
      Example:
    
      track 0 1 1 1 muon energy 10000 nodelta
      Call book_histogram(size,100)
      For i From 1 To 100 Do
         Call new_track
         Until done Do
            Call get_cluster(xcls,ycls,zcls,npair,ecls,done)
            If done Then Iterate
            Call fill_histogram(size,npair)
         Enddo
      Enddo
      !opt log-y
      Call plot_histogram(size,`Cluster size`,...
         `Cluster size distribution`)
    
      This example shows how one can obtain the cluster size
      distribution for tracks generated by the Heed program.
      Since Heed doesn't generate clusters but always delta
      electrons (they usually have a very short range), we use
      the NODELTA option on the TRACK command. This compresses
      the delta electrons into clusters.
    

    Additional Information on:

  • xyz
  • ecls
  • npair
  • done

  • GET_DRIFT_LINE

      Returns the (x,y,z,t) coordinates of the current drift line.
      All 4 arguments are 1-dimensional vectors that are created
      by the procedure.
    
      Note: if polar coordinates are used, then (x,y) represent
      the internal coordinates
    
           (rho,phi)=(log(sqrt(x**2+y**2),arctan(y/x))
    
      These can be converted to Cartesian or polar coordinates with
      the INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.
    
      Format:
    
      CALL GET_DRIFT_LINE(x, y, z, t)
    
      Example:
    
      Say "Please enter (x,y) of the starting point"
      Parse terminal x_start y_start
      Call drift_electron(1,1,status,time)
      Call get_drift_line(x,y,z,t)
      Call plot_graph(t,x,`Time [microsec]`,`x [cm]`,`x vs time`)
      Call plot_comment(`UP-LEFT`,`Status: `/status)
      Call plot_comment(`DOWN-LEFT`,`Drift time: `/string(time)/` [microsec]`)
      Call plot_comment(`UP-RIGHT`, `From (x,y)=(`/string(x_start)/`,`/...
         string(y_start)/`)`)
      Call plot_end
    
      A way to plot the relation between the x-coordinate of a drift
      line and the drift time.
    

    GET_E/P_TABLE

      Returns the current table of E/p points.
    
      One can use the GET_GAS_DATA procedure to obtain the
      pressure in order to convert ep to an electric field.
    
      Format:
    
      CALL GET_E/P_TABLE(ep)
    

    GET_GAS_DATA

      Returns the pressure, temperature and identifier of the gas.
    
      Format:
    
      CALL GET_GAS_DATA(pressure, temperature, identifier)
    
      Example:
    
      Call get_gas_identifier(p, t, gasid)
      Say "Gas identifier is {gasid}."
    

    GET_HISTOGRAM

      Retrieves an histogram from disk. After retrieval, the histogram
      can further be filled etc.
    
      Format:
    
      CALL GET_HISTOGRAM(reference, file [, member])
    

    Additional Information on:

  • reference
  • file
  • member

  • GET_MATRIX

      GET_MATRIX is used to recover matrices from a disk file to which
      they have been written with the WRITE_MATRIX procedure.
    
      Format:
    
      CALL GET_MATRIX(matrix, file [, member])
    
      Example:
    
      See WRITE_MATRIX.
    

    Additional Information on:

  • matrix
  • file
  • member

  • GET_PERIODS

      Returns information periodicities. The first and third
      argument are logicals that are set to TRUE if the
      corresponding periodicity is present in the cell. The
      second and fourth argument are set to the length of
      one period, if existing, and in internal coordinates.
    
      Format:
    
      CALL GET_PERIODS(yn_x, s_x, yn_y, s_y)
    

    GET_RAW_SIGNAL

      Copies a raw signal to a 1-dimensional matrix. Raw signals serve
      as ingredient to compute actual signals and are mainly of use if
      you wish to do such calculations outside Garfield.
    
      Format:
    
      CALL GET_RAW_SIGNAL(type, sense_wire, avalanche_wire, angle,...
           time, signal)
    

    Additional Information on:

  • type
  • sense_wire
  • avalanche_wire
  • angle

  • GET_SIGNAL

      Copies a signal to a (set of) 1-dimensional matrices.
    
      Format:
    
      CALL GET_SIGNAL(wire, time, direct [, cross-induced])
    
      Example: see LIST_RAW_SIGNALS.
    

    Additional Information on:

  • wire

  • GET_X_PLANE_DATA

      Returns information on all planes at constant x or r
      present in the cell.
    
      Internal coordinates are used for the plane locations.
      Use the INTERNAL_TO_POLAR procedure to convert to, for
      instance, polar coordinates.
    
      Format:
    
      CALL GET_X_PLANE_DATA(yn_1, x_1, V_1, yn_2, x_2, V_2)
    
      Example:
    
      Call get_cell_data(wires,type,coord,id)
      Call get_x_plane_data(yn1,x1,V1, yn2,x2,V2)
      If 'coord="Polar"' Then
         If yn1 Then Say "There is a plane at r={exp(x1)} and with V={V1}."
         If yn2 Then Say "There is a plane at r={exp(x2)} and with V={V2}."
      Else
         If yn1 Then Say "There is a plane at x={x1} and with V={V1}."
         If yn2 Then Say "There is a plane at x={x2} and with V={V2}."
      Endif
    

    GET_Y_PLANE_DATA

      Returns information on all planes at constant y or phi
      present in the cell.
    
      Internal coordinates are used for the plane locations,
      use the INTERNAL_TO_POLAR procedure to convert to polar
      coordinates.
    
      Format:
    
      CALL GET_Y_PLANE_DATA(yn_1, y_1, V_1, yn_2, y_2, V_2)
    
      Example:
    
      Call get_cell_data(wires,type,coord,id)
      Call get_y_plane_data(yn1,y1,V1, yn2,y2,V2)
      If 'coord="Polar"' Then
         If yn1 Then Say "There is a plane at phi={180*y1/pi} and with V={V1}."
         If yn2 Then Say "There is a plane at phi={180*y2/pi} and with V={V2}."
      Else
         If yn1 Then Say "There is a plane at y={y1} and with V={V1}."
         If yn2 Then Say "There is a plane at y={y2} and with V={V2}."
      Endif
    

    GET_WIRE_DATA

      Returns information about wire IW: the location in internal
      coordinates, the potential, the diameter, the charge, the wire
      code, the length, the stretching weight and the density.
    
      If the cell has been entered in polar coordinates, then the
      wire location is returned in internal coordinates. These can
      be converted to Cartesian or polar coordinates with the
      INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.
    
      All arguments are optional.
    
      Format:
    
      CALL GET_WIRE_DATA(iw, x_iw, y_iw, V_iw, d_iw, q_iw, code_iw,...
           length, weight, density)
    
      Example:
    
      Call get_cell_data(nwire,dummy,dummy,id)
      Say "List of wires with a negative charge:"
      For i From 1 To nwire Do
         Call get_wire_data(i,xw,yw,vw,dw,qw,codew)
         If qw>0 Then Iterate
         Say "Wire {i} at (x,y)=({xw,yw}), type {codew}"
      Enddo
    
      This example shows how one can produce a list of the wires
      that have a negative charge. One could also select a sense
      wire and store its coordinates using this technique.
    

    HISTOGRAM_TO_MATRIX

      Makes a matrix copy of an histogram, optionally returning
      the range of the histogram. The histogram is not affected
      by this operation.
    
      Format:
    
      CALL HISTOGRAM_TO_MATRIX(hist, matrix [, min [, max]])
    
      Example:
    
      Call book_histogram(ref1,10,0,1)
      For i From 1 To 1000 Do
         Call fill_histogram(ref1,rnd_uniform)
      Enddo
      Call plot_histogram(ref1)
      Call histogram_to_matrix(ref1,a,min,max)
      Call matrix_to_histogram(a,min,max,ref2)
      Call plot_histogram(ref2)
    
      First, we book an histogram and fill it with uniformly
      distributed random numbers. The histogram is then copied
      to a matrix A, and then copied back to a histogram. Both
      histograms are plotted to check they are indeed the same.
    

    INQUIRE_FILE

      Tells whether a file exists or not.
    
      The file does not have to be a Garfield library. If you wish to
      test the presence of, for instance, a gas description is a given
      library, it would be better to use the INQUIRE_MEMBER call.
    
      Format:
    
      CALL INQUIRE_FILE(file_name, exist)
    
      Example:
    
      &CELL
      Call inquire_file(`new_cell`,exist)
      If exist Then
         % del "dc1.lib" cell
         < new_cell
         write "dc1.lib" cell
      Else
         get "dc1.lib" cell
      Endif
    
      In this example a cell description is retrieved from a
      library called dc1.lib, unless a file called new_cell is
      found. In that case, the cell description is deleted from
      the library, the new description is read and stored in
      compact format in the library.
    

    INQUIRE_HISTOGRAM

      Returns some information on a histogram that must be in storage.
    
      The first 2 arguments are mandatory, the rest is optional.
    
      Format:
    
      CALL INQUIRE_HISTOGRAM(reference, exists, range set, channels,
           minimum, maximum, entries, average, standard deviation)
    

    Additional Information on:

  • reference

  • INQUIRE_MEMBER

      Tells whether a member in a library exists or not.
    
      The return flag EXIST is set to True only if all of the
      following conditions are fulfilled:
    
      - the file exists
      - the file can be identified as a Garfield library
      - the library contains the specified member
      - the type of the member matches the type in the argument list
    
      Otherwise EXIST is set to False and the arguments MEMBER,
      REMARK, DATE and TIME are not touched.
    
      Format:
    
      CALL INQUIRE_MEMBER(file, member, type, exist ...
           [,remark [, date [, time]]])
    
      Example:
    
      &GAS
      Call inquire_member(`GAS.DAT`,`XE50E50`,`GAS`,exist)
      If exist Then
         get gas.dat xe50e50
      Else
         pressure 500
         temperature 300
         magboltz xenon 50 ethane 50
         write gas.dat xe50e50
      Endif
    
      In this example the existence of a member called XE50E50 in
      a library called GAS.DAT is checked. Since the type is set
      to GAS, only compact gas descriptions are considered.
      If the member exists, the data is read, otherwise a
      new table is prepared and is then written to the file.
    

    Additional Information on:

  • file
  • member
  • type
  • remark
  • date
  • time

  • INQUIRE_TYPE

      The INQUIRE_TYPE procedure can be used to determine whether
      a given global variable exists and, if it does, what type it
      has.
    
      The return parameter, type, can have the following values:
      `String`, `Number`, `Logical`, `Histogram`, `Matrix`,
      `Undefined` and `# Invalid`.
    
      Format:
    
      CALL INQUIRE_TYPE(variable, type)
    
      Example:
    
      Call book_histogram(hist,10,0,10)
      Call inquire_type(hist,type)
      Say "Type is {type}"
    

    INTEGRATE_CHARGE

      Integrates, depending on the format that is used, the charge in
      - a cylindrical area centered at (x,y) with radius r
      - a spherical area centered at (x,y,z) with radius r
    
      In the 2-dimensional case, the charge is normalised such that
      a line charge with potential V = 1/2.pi log(x^2 + y^2) would
      return a charge of 1. In the 3-dimensional case, a point charge
      with potential V = 1/4.pi 1/(x^2+y^2+z^2) would also yield a
      total charge of 1. These normalisations should match the fields
      that are used for wires and space charges respectively.
    
      Integration is performed using 6-point Gaussian quadrature over
      50 equal intervals for the 2-dimensional case, and over 20 equal
      intervals both in phi and in theta for the 3-dimensional case.
    
      Format:
    
      CALL INTEGRATE_CHARGE(x, y, [z,] r, q)
    
      Example:
    
      &CELL
      rows
      s * * 1 1 1000
      s * * -1 -1 -1000
    
      opt cell-print
    
      &OPT
      charges
      2 2 2 1
      3 2 3 4.5
    
      &FIELD
      Call integrate_charge(1.1, 0.5, 0.8, q)
      Say "One wire: {q}"
      Call integrate_charge(5, 2, 2.5, 3.5, q)
      Say "Both point charges together: {q}"
    
      (Verifies the line and point charges.)
    

    INTEGRATE_FLUX

      Integrates the flux of the E field over a parallelogram.
      The parallelogram has (x0,y0,z0) as one of its edges while
      the adjacent edges are (x0+dx1,y0+dy1,z1+dz1) and
      (x0+dx2,y0+dy2,z1+dz2). The flux is returned in Volt.cm.
    
      Integration is performed using 6-point Gaussian quadrature
      over (nu x nv) equal intervals along the two sides of the
      reactangle. The arguments nu and nv are optional. They are
      by default set to 20.
    
      This procedure is used to investigate transmission losses.
    
      Format:
    
      CALL INTEGRATE_FLUX(x0,y0,z0, dx1,dy1,dz1, dx2,dy2,dz2, flux
           [, nu [, nv]])
    
      Example:
    
      &CELL
      plane x=-1 v=-1000
      plane x=+1 v=+1000
      rows
      s * * 20 20 0
    
      &FIELD
      Call flux(0,-1,-1, 0,2,0, 0,0,2, flux)
      Say "Flux={flux} [V.cm]"
    
      In a parallel plate chamber, with a field of 1 kV/cm, we compute
      the flux through a rectangle of 2 cm by 2 cm. The flux is equal
      to 1000 V/cm x 4 cm^2 = 4000 V.cm
    

    INTERNAL_TO_CARTESIAN

      Applies the conformal mapping of internal (rho,phi) coordinates
      to Cartesian (x,y) coordinates. The (rho,phi) coordinates are
      used internally in the program when the cell is described in
      polar coordinates.
    
      Internal coordinates are related to Cartesian coordinates by:
    
           x = cos(phi)*exp(rho)        [phi in radian, x in cm]
           y = sin(phi)*exp(rho)        [phi in radian, y in cm]
    
      The input arguments of this procedure can be either of type Number
      or of type Matrix. If the input type is Matrix, then the two input
      matrices must have the same total number of elements. The output
      matrices will have the same structure as the first input matrix.
    
      The abbreviated procedure name RTC is also accepted.
    
      Format:
    
      CALL INTERNAL_TO_CARTESIAN(rho,phi,x,y)
    

    INTERNAL_TO_POLAR

      Converts internal (rho,phi) coordinates to polar (r,phi')
      coordinates. The (rho,phi) coordinates are used internally in
      the program when the cell is described in polar coordinates.
    
      Internal coordinates are related to polar coordinates by:
    
           r    = exp(rho)       [dimensions not defined]
           phi' = 180*phi/pi     [phi' in degrees]
    
      The input arguments of this procedure can be either of type Number
      or of type Matrix. If the input type is Matrix, then the two input
      matrices must have the same total number of elements. The output
      matrices will have the same structure as the first input matrix.
    
      The abbreviated procedure name RTP is also accepted.
    
      Format:
    
      CALL INTERNAL_TO_CARTESIAN(rho,phi,x,y)
    

    INTERPOLATE

      The INTERPOLATE procedure performs linear interpolation in
      matrices of up to 5 dimensions for an arbitrary number of
      points.
    
      This procedure is intended for interpolations in multi-dimensional
      matrices for a series of points at the time. For single-point
      interpolations in 1-dimensional arrays, it is easier to use the
      INTERPOLATE_1, INTERPOLATE_2, INTERPOLATE_3 and INTERPOLATE_4
      procedures which furthermore permit higher order polynomial
      interpolation.
    
      Format:
    
      CALL INTERPOLATE(matrix, ord_1, ... ord_n, points, out)
    
      Example:
    
      Call get_matrix(time,`transfer.mat`)
      Call get_matrix(z,`transfer.mat`)
      Call get_matrix(delta,`transfer.mat`)
    
      Say "Please enter the value of z for which you wish the transfer function:"
      Global OK=false
      Global z_hit=-1
      While ^OK Do
         Parse terminal z_hit
         Global OK=z_hit>=0 & z_hit<=6
         If ^OK Then Say "Please enter a value between 0 and 6 m."
      Enddo
    
      Call dimensions(time,ndim_time,dim_time)
      Call book_matrix(point,2,dim_time[1])
      Call delete_matrix(dim_time)
      Global point[1;]=z_hit
      Global point[2;]=time
    
      Call interpolate(delta,z,time,point,trans)
      Call delete_matrix(point)
    
      The matrix delta contains the delta-responses of a tube
      measured at various points along the tube (written z)
      and as function of time (written time). The purpose of
      the example is to show how one can compute the delta-
      response for intermediate values of z by interpolation.
    

    Additional Information on:

  • matrix
  • ord
  • points
  • out

  • INTERPOLATE_i

      A series of 4 procedures (INTERPOLATE_1, INTERPOLATE_2,
      INTERPOLATE_3 and INTERPOLATE_4) which perform 1-dimensional
      local linear, parabolic, cubic and quartic polynomial
      interpolations.
    
      For (linear) interpolation in higher-dimensional matrices,
      use the INTERPOLATE procedure.
    
      Format:
    
      CALL INTERPOLATE_i(x_vector, y_vector, x, y)
    
      Example:
    
      sel 1
      check wire keep-results
      Call interpolate_2(phi_1, e_1, pi/2, e90)
      Call interpolate_2(phi_1, e_1, 3*pi/2, e270)
      Say "Electric field at 90 degrees is {e90} and at 270 degrees {e270}."
    
      In this example, one computes the field at the surface of wire
      1 and asks to save the results in a series of vectors. Since
      the values at 90 and 270 degrees are not present in these vectors,
      one uses one of the INTERPOLATE_i procedures to interpolate for
      these angles.
    

    ION_MOBILITY

      Returns the ion mobility, if available, for a given value
      of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).
    
      If the field is specified with vectors, then the result will
      also be a vector. Otherwise the result will be a scalar. It
      is permitted to specify 1 or 2 components of the field with
      scalars and the other(s) with vectors. The result will still
      be a vector in that case.
    
      The electric field should be in V/cm, the ion mobility is
      returned in cm2/V.microsec.
    
      Format:
    
      CALL ION_MOBILITY(ex, ey, ez, mobility)
    

    LIST_HISTOGRAMS

      Prints a summary of all histograms currently in storage.
    
      Format:
    
      CALL LIST_HISTOGRAMS
    

    LIST_MATRICES

      LIST_MATRICES prints an overview of matrices currently
      in memory and of the global variables associated with
      them.
    
      Format:
    
      CALL LIST_MATRICES
    
      Example:
    
      Call book_matrix(a,2,3,4,5)
      Call list_matrices
      Call delete_matrix(a)
      Call list_matrices
    

    LIST_RAW_SIGNALS

      Lists the raw signals that are currently in store.
    
      Format:
    
      CALL LIST_RAW_SIGNALS
    
      Example:
    
      &SIGNAL
      track 0.5 -0.5 0.5 0.5
      ava exp 10000
      res 0 0.01 200
      opt nocl-pr nocl-pl
      sel 1
      signal
      Call list_raw_signals
      Call get_raw_signal(`ion`,1,1,0,time,sig)
      Call plot_frame(0,0,4,10,` `,` `,` `)
      Call plot_line(time,sig)
      Call plot_end
    
      In this example, the LIST_RAW_SIGNALS call is used to determine
      which raw signals are currently available. Then, one of them is
      retrieved and plotted.
    

    LONGITUDINAL_DIFFUSION

      Returns the longitudinal diffusion, if available, for a given
      value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).
    
      If the field is specified with vectors, then the result will
      also be a vector. Otherwise the result will be a scalar. It
      is permitted to specify 1 or 2 components of the field with
      scalars and the other(s) with vectors. The result will still
      be a vector in that case.
    
      The electric field should be in V/cm, the diffusion is
      returned in sqrt(cm).
    
      SIGMA_L can be typed as a synonym to LONGITUDINAL_DIFFUSION.
    
      Format:
    
      CALL LONGITUDINAL_DIFFUSION(ex, ey, ez, sigma_l)
    

    LORENTZ_ANGLES

      Returns the Lorentz angles, if available, for a given value
      of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).
    
      If the field is specified with vectors, then the result will
      also be a vector. Otherwise the result will be a scalar. It
      is permitted to specify 1 or 2 components of the field with
      scalars and the other(s) with vectors. The result will still
      be a vector in that case.
    
      The electric field should be in V/cm, the Lorentz angles are
      returned in radians.
    
      Format:
    
      CALL LORENTZ_ANGLES(ex, ey, ez, angle)
    

    MAGNETIC_FIELD

      Returns the magnetic field vector at a given point. This procedure
      assumes that the z-coordinate of the point is equal to 0.
    
      Format:
    
      CALL MAGNETIC_FIELD(x, y, bx, by, bz [, b])
    

    Additional Information on:

  • coordinates
  • field

  • MAGNETIC_FIELD_3

      Returns the magnetic field vector at a given point.
    
      Format:
    
      CALL MAGNETIC_FIELD_3(x, y, z, bx, by, bz [, b])
    

    Additional Information on:

  • coordinates
  • field

  • MAP_INDEX

      Returns the index of the triangle or tetrahedron in which a
      point is located, and optionally also the local triangular or
      tetrahedron coordinates of the point.
    
      This procedure should only be called if a field map has been
      defined. When the field map is 2-dimensional, only (x,y) should
      be specified and only (t1,t2,t3) will be returned. If the map
      is 3-dimensional, all 3 coordinates (x,y,z) must be provided
      and 4 tetrahedron coordinates will be returned.
    
      This procedure is meant for debugging.
    
      Format:
    
      CALL MAP_INDEX(x, y [, z], index, [t1, t2, t3 [,t4]])
    

    MATRIX_TO_HISTOGRAM

      Copies a matrix to a histogram, with the specified range.
      The range is a required parameter for this procedure. The
      matrix is not affected by this operation.
    
      The matrix should be 1-dimensional, if you give a matrix
      with a higher number of dimensions, then it will be
      unfolded.
    
      Format:
    
      CALL MATRIX_TO_HISTOGRAM(matrix, min, max, hist)
    
      Example:
    
      See HISTOGRAM_TO_MATRIX.
    

    MULTIPLY_MATRICES

      (Not yet available)
    

    NEW_TRACK

      This procedure reinitialises cluster generation along the
      current track.
    
      The procedure should be called before any call to GET_CLUSTER.
    
      Format:
    
      CALL NEW_TRACK
    
      Example:
    
      See GET_CLUSTER
    

    PLOT_AREA

      Plots an area that is delineated by the series of points
      given as argument. At least 3 points should be present in
      the argument list, but many more can be specified.
    
      This procedure should only be called after a call to PLOT_FRAME.
    
      Format:
    
      CALL PLOT_AREA(x1, y1, x2, y2, ..., x_n, y_n [, area_type])
    
      Example:
    
      !rep times-roman character-height 0.075 ch-exp {1.2/8.5}
      !rep box polyline-col background
      !rep grid polyline-col background
      !rep numbers text-col background
      Call plot_frame(0,0,1.2,8.5,` `,` `,` `)
      For i from 0 to 1.01 step 0.2 do
         For j from 0 to 1.01 step 0.2 do
            For k from 0 to 1.01 step 0.2 do
               !colour a red {i} green {j} blue {k}
               !rep wires fill-area-colour a fill-area-int-style solid
               Call plot_area(j,7*i+k, j,7*i+k+0.2, j+0.2,7*i+k+0.2, ...
                    j+0.2,7*i+k, j,7*i+k, `WIRES`)
               Call plot_text(j+0.1,7*i+k+0.1, ...
                    `R=`/string(i)/`, B=`/string(k)/`, G=`/string(j), ...
                    `TIMES-ROMAN`,`CENTER-HALF`)
            Enddo
         Enddo
      Enddo
      Call plot_end
    
      This example illustrates how one can generate an RGB colour map.
      The colour A is repeatedly redefined in the loop and is used to
      modify also the representation of WIRES (one of the few pre-
      defined FILL-AREA representations). In each box with a given
      colour, the RGB value is plotted in TIMES-ROMAN. You may have
      to change this name depending on the graphics system that you
      are using.
    

    Additional Information on:

  • area_type

  • PLOT_CELL

      Plots the layout of the cell. All arguments are optional.
      If the range (xmin,ymin) to (xmax,ymax) is omitted, then
      the full range is assumed. If the title is omitted, then
      the cell identifier is taken (if not blank), otherwise the
      string "Layout of the cell".
    
      If the cell has been entered in polar coordinates, then the
      range to be plotted should be specified in internal coordinates.
      These can be obtained from Cartesian or polar coordinates with
      the CARTESIAN_TO_INTERNAL and POLAR_TO_INTERNAL procedures.
    
      Format:
    
      CALL PLOT_CELL([xmin, ymin, xmax, ymax] , [title])
    
      Examples:
    
      Call plot_cell(`Layout`)
      Call plot_cell(1,1,2,2)
      Call plot_cell(1,1,2,2,`Layout`)
    

    PLOT_COMMENT

      Each plot frame has room for 4 comments, placed beneath the
      title: 2 on the left, 2 on the right, in both cases 2 lines.
    
      Format:
    
      PLOT_COMMENT(place, text)
    
      Example:
    
      Call plot_frame(1,1,2,2,`x`,`y`,`Title`)
      Call plot_comment(`up-left`,`Made on `/machine)
      Call plot_comment('down-right`,`Time left: `/string(time_left))
      Call plot_end
    
      Will place a comment string on the left in the top row that
      reads (on a Vax) "Made on Vax".
    

    Additional Information on:

  • place
  • text

  • PLOT_CONTOURS

      Plots a matrix as a set of contours. The precise way the contours
      is appears and the set of options that is honoured, depends
      on the underlying graphics package.
    
      Format:
    
      CALL PLOT_CONTOURS(matrix [, n_contour [, options
           [, x-vector [, y_vector
           [, x-label [, y-label [, title ]]]]]]])
    
      Example:
    
      Call book_matrix(a,30,30)
      Call plot_contours(a)
    

    Additional Information on:

  • matrix
  • n_contours
  • options
  • x-vector
  • y-vector
  • x-label
  • y-label
  • title

  • PLOT_DRIFT_AREA

      Plots a frame in the current projection of the drift area.
    
      Format:
    
      CALL PLOT_DRIFT_AREA([title])
    
      Example:
    
      area -1 -1 -2 1 1 2 view x+2*y+3*z=5
      call plot_drift_area
    

    PLOT_DRIFT_LINE

      Plots a projection of the current drift line. The coordinate axes
      should have been plotted before, for instance with PLOT_DRIFT_AREA.
      If the cell is in polar coordinates, then the drift line will also
      be plotted in such a coordinate frame.
    
      The desired projection should be set with the AREA command.
    
      Format:
    
      CALL PLOT_DRIFT_LINE
    
      Example:
    
      Global x0=0.001
      Global y0=0.028
      Call plot_cell(-0.02, -0.015, 0.02, 0.032)
      For i From 1 To 50 Do
         Call drift_mc_electron(x0, y0, 0, status, time)
         Call plot_drift_line
      Enddo
      Call plot_end
    
      This examples would make a plot of 50 Monte Carlo integrated
      drift lines all starting from the same point (x0,y0). One can
      of course exand the example by adding histograms of the drift
      time and the arrival point.
    

    PLOT_END

      This procedure should be called once your plot is ready to empty
      the graphics buffer.
    
      Yoy may optionally specify a string as argument. The string will
      be entered in the list of plots that is printed at the end of the
      job output.
    
      Format:
    
      CALL PLOT_END( [string] )
    

    PLOT_ERROR_BAND

      Plots an error band, an area usually filled with a light
      colour, to indicate the uncertainty in a calculated curve,
      for instance due to uncertainty in the parameters used
      to compute the curve.
    
      The area is filled with a colour according to fill area
      representation ERROR-BAND, and then surrounded by a curve
      according to polyline representation ERROR-BAND.
    
      Filling the area with yellow, gives good results when the
      plot is included in a black and white PostScript document:
      the area then appears as light grey.
    
      This call would typically be combined with PLOT_ERROR_BAR.
    
      Format:
    
      CALL PLOT_ERROR_BAND(x, y1, y2)
    
      Example:
    
      Call plot_frame(0,0,5,5,`x`,`y`,`title`)
      Call book_matrix(x1,50)
      Global x1=x1/10
      Global y1=1+x1**2/10
      Global y2=y1*1.2
      Call plot_error_band(x1,y1,y2)
      Call plot_end
    
      In this example, a matrix, called X1, is booked with length 50.
      The matrix is initially filled with integer numbers from 1 to 50.
      The values are rescaled by dividing them by 10, then a parabolic
      error band Y1 to Y2 is constructed with 20 % uncertainty.
    

    Additional Information on:

  • vectors

  • PLOT_ERROR_BAR

      Plots a series of error bars. Only the (x,y) coordinates of the
      center must be present, but one can specify both symmetric and
      asymmetric error bars. Optionally, one may also provide the size
      and appearance of the error bar.
    
      Format:
    
      CALL PLOT_ERROR_BAR(x, y [, ex-, ey- [, ex+, ey+]] [, type [, size]])
    
      Example:
    
      read-vector x y ex1 ey1 ex2 ey2
      1 1 0.5 0.5 0.25 0.25
      2 2 0.5 0.25 0.5 0.25
    
      call plot_frame(0,0,5,5,`x`,`y`,`title`)
      call plot_error_bars(x,y,ex1,ey1,`circle`,0.02)
      call plot_error_bar(x+2,y,ex1,ey1,ex2,ey2,`square`)
      call plot_end
    

    Additional Information on:

  • center
  • errors
  • type
  • size

  • PLOT_FRAME

      Draws a set of Cartesian coordinate axes with labels.
    
      Call PLOT_END to end the plot.
    
      Format:
    
      CALL PLOT_FRAME(xmin, ymin, xmax, ymax ...
           [, x_label [, y_label [, title]]])
    

    PLOT_GRAPH

      Draws a graph of one vector against another vector.
    
      The scales are chosen automatically on the basis of the range
      of the vectors and axes are plotted accordingly. PLOT_FRAME
      should not be called prior to PLOT_GRAPH.
    
      The graph is left open after the call and further elements can
      be added to the plot. PLOT_END should be called to end the plot.
    
      The curve is drawn with polyline representation FUNCTION-1.
    
      Format:
    
      CALL PLOT_GRAPH(x_vector, y_vector [, x_label [, y_label, [,title]]])
    
      Example:
    
      Global n=20
      Call book_matrix(x,n)
      Call book_matrix(y,n)
      Global m=3
      For i From 1 To n Do
         Global x[i]=cos(m*2*pi*i/(n-1))
         Global y[i]=sin(m*2*pi*i/(n-1))
      Enddo
      Call plot_graph(x,y)
      !rep circle polymarker-colour green
      Call plot_marker(x,y,`circle`)
      Call plot_end
    
      The plot in this example is a kind of star pattern. The axis
      labels are omitted and will therefore be replaced by X and Y,
      the names of the variables that have been plotted.
    

    Additional Information on:

  • labels
  • title

  • PLOT_HISTOGRAM

      Plots an histogram with the specified label along the x axis and
      with the given title. Calling this procedure does not interfere with
      filling of the histogram but an histogram will only be printed if
      the range has been set (applicable for auto range histograms only).
    
      Format:
    
      CALL PLOT_HISTOGRAM(reference [, x-title [, title ...
           [, frame, [close]]]])
    
      Example:
    
      !col red red 1 blue 0 green 0
      !col blue red 0 blue 1 green 0
      !col green red 0 blue 0 green 1
      !rep function-1 polyline-colour green
      Call hplot(all_1,"Time [microsec]","ARRIVAL TIME SPECTRUM", ...
           True,False)
      !rep function-1 polyline-colour red
      Call hplot(sel_1," "," ",False,False)
      !rep function-1 polyline-colour blue
      Call hplot(sel_2," "," ",False,True)
    
      In this example, the overall arrival time spectrum is plotted
      together with the arrival time distributions for a number of
      selected electron. The 3 histograms are distinghuised by colour.
    

    Additional Information on:

  • reference
  • title
  • frame
  • close

  • PLOT_LINE

      Connects a series of points either by straight line segments,
      or by a cubic spline. Either two 1-dimensional matrices of
      equal length or at least two sets of (x, y) pairs should be
      given as argument. The two formats can not be mixed.
    
      This procedure should only be called after a call to PLOT_FRAME.
    
      Formats:
    
      CALL PLOT_LINE(x1, y1, x2, y2, ..., x_n, y_n [, option])
      CALL PLOT_LINE(x_vector, y_vector [, option])
    
      Example 1:
    
      !col cyan red 0.8 green 1 blue 1
      !rep function-4 polyline-colour cyan
      call plot_line(0,0, 1,0, 0,1, 1,1, 0,0, `function-4`)
    
      A colour called CYAN is defined, this colour is used to
      modify the appearance of FUNCTION-4 polylines. This polyline
      representation is used to produce a figure on the screen.
    
      Example 2:
    
      call book_matrix(time,20)
      read-vector time
      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
    
      Call plot_frame(0,-1.1,21,1.1,`Time`,`Sinus`,`A curve`)
      Call plot_line(time,sin(time/3),`FUNCTION-1`)
      Call plot_end
    
      This example shows how one can plot a simple curve: the
      vector TIME is declared and initialised with the numbers
      1 through 20. This is actually not necessary since a
      matrix has this contents when it is created. Then, a plot
      is made of TIME vs sin(TIME/3). A slightly simpler way to
      achieve this result would have been to use PLOT_GRAPH.
    

    Additional Information on:

  • option

  • PLOT_MARKER

      Plots a series of markers. This procedure should only be called
      after a call to PLOT_FRAME. This procedure can be used both with
      a series of (x, y) pairs as argument, and with a pair of
      1-dimensional matrices.
    
      Formats:
    
      CALL PLOT_MARKER(x1, y1, x2, y2, x3, y3, ... [, marker_type])
      CALL PLOT_MARKER(x_vector, y_vector [, marker_type])
    
      Example:
    
      Global n=50
      Call book_matrix(x,n)
      Call book_matrix(y,n)
      For i From 1 To n Do
         Global x[i]=i
         Global y[i]=rnd_gauss
      Enddo
      Call plot_frame(number(x[1]),-3,number(x[n]),3,...
         `Time`,`Random`,`Scattered points`)
      !rep circle polymarker-colour orange
      Call plot_marker(x,y,`CIRCLE`)
      Call plot_end
    
      First, 2 matrices are created. One is filled with the numbers
      1-n, the other with Gaussian distributed random numbers. Then,
      the pairs are plotted as orange circles.
    

    Additional Information on:

  • marker_type

  • PLOT_SURFACE

      Plots a 3-dimensional surface. The precise way the surface
      is rendered and the set of options that is honoured, depends
      on the underlying graphics package.
    
      Format:
    
      CALL PLOT_SURFACE(matrix ...
           [, theta [, phi ...
           [, x-vector [, y_vector ...
           [, x-label [, y-label [, title]]]]]]])
    
      Example:
    
      Call book_matrix(a,30,30)
      Call plot_surface(a)
    

    Additional Information on:

  • matrix
  • theta
  • phi
  • x-vector
  • y-vector
  • x-label
  • y-label
  • title

  • PLOT_TEXT

      Plots a string in the frame that should previously have been
      opened with PLOT_FRAME.
    
      On some graphics systems (provided that the graphics option
      DISPLAY-CONTROL-CHARACTERS is on, this is by default the case)
      special symbols are available through the following mechanisms:
    
      a. In units (recognised by the squared brackets that enclose
         them), the strings 'cm2', 'cm3', 'micron', 'microsec' and
         'microamp', are shown in their usual way (superscript 2 for
         'cm2', Greek mu for 'micron' etc.
      b. Some particle names (e.g. electron-, mu+, tau-) as well as
         some chemical compounds (e.g. CO2, C3H8) are shown the way
         they are normally printed with superscripts to indicate
         the charge and subscripts showing the number of atoms per
         molecule.
      c. Greek letters, diacritics and ligatures are accessible as
         SGML entities, e.g. &Ksi; &eacute; and &szlig;. For a list
         of SGML entities, see for instance:
         http://home.eclipse.net/~lionheart/html/entities.html
    
      Format:
    
      CALL PLOT_TEXT(x, y, string [, font [, alignment [, orientation]]])
    
      Example:
    
      Call plot_text(0.5, 0.5, `Some text`, `ROMAN`, `LEFT-BASE`)
    
      The string "Some text" will be plotted horizontally with its lower
      left corner at (0.5,0.5).
    

    Additional Information on:

  • font
  • alignment
  • orientation

  • PLOT_TRACK

      This procedure plots a projection of the track according
      to the current settings of the AREA command of the drift
      section.
    
      For most track models, this will simply be a line from the
      starting point of the track to the end point.
    
      If the track is generated with Heed, also the photons and
      the electrons (delta, Auger) are shown. To generate a track
      with Heed, you must first call NEW_TRACK and then at least
      once GET_CLUSTER, even if you don't use the data returned
      by the latter procedure.
    
      The path of the particle is shown with representation TRACK,
      Auger electrons with AUGER, delta electrons (i.e. ionisation
      deposits) with DELTA and the photons with GAMMA.
    
      Format:
    
      CALL PLOT_TRACK
    
      Example:
    
      For i From 1 To nstat Do
         If 'i=10*entier(i/10)' Then Say "Iteration {i}"
         Call plot_cell(-0.1,-0.01,0.1,0.3)
         Call new_track
         Do
            Call get_cluster(xcls,ycls,zcls,npair,done)
            If done Then
               Leave
            Else
               For n From 1 To npair Do
                 Call drift_mc_electron(xcls, ycls, zcls, status, time)
                 Call plot_drift_line
               Enddo
            Endif
         Enddo
         Call plot_track
         Call plot_end
      Enddo
    
      (This example shows how one can make the same kind of plot
      as DRIFT TRACK by calling procedures.)
    

    POLAR_TO_CARTESIAN

      Converts polar (r,phi) coordinates to Cartesian (x,y) coordinates.
    
      The input arguments of this procedure can be either of type Number
      or of type Matrix. If the input type is Matrix, then the two input
      matrices must have the same total number of elements. The output
      matrices will have the same structure as the first input matrix.
    
      The abbreviated procedure name PTC is also accepted.
    
      Format:
    
      CALL POLAR_TO_CARTESIAN(r,phi,x,y)
    

    POLAR_TO_INTERNAL

      Converts polar (r,phi) coordinates to (rho,phi') coordinates that
      are used internally when dealing with cells in polar coordinares.
      The internal coordinates a conformal mapping of (x,y) coordinates.
    
      If the condition r>0 is not met, then the global variable OK is
      set to False, otherwise to True.
    
      Internal coordinates are related to polar coordinates by:
    
           rho  = log(r)        [dimension not defined]
           phi' = pi*phi/180    [radians]
    
      The input arguments of this procedure can be either of type Number
      or of type Matrix. If the input type is Matrix, then the two input
      matrices must have the same total number of elements. The output
      matrices will have the same structure as the first input matrix.
    
      The abbreviated procedure name PTR is also accepted.
    
      Format:
    
      CALL POLAR_TO_INTERNAL(r,phi,rho,phi')
    

    PRINT

      The PRINT procedure simply prints the arguments it is given.
    
      Format:
    
      CALL PRINT(any number of arguments)
    

    PRINT_HISTOGRAM

      This procedure prints the histogram called "reference". Calling
      this procedure does not interfere with filling of the histogram
      but an histogram will only be printed if the range has been set
      (applicable for auto range histograms only).
    
      Format:
    
      CALL PRINT_HISTOGRAM(reference [, x-title [, title]])
    

    Additional Information on:

  • reference

  • PRINT_MATRIX

      Prints one or more matrices.
    
      Format:
    
      CALL PRINT_MATRIX(matrix_1, matrix2, ...)
    
      Example:
    
      Call book_matrix(a,2,3)
      Call print_matrix(a)
    
      A matrix called A is booked, and is then immediately printed.
      This shows how matrices are initialised.
    

    PROJECT_LINE

      Projects a line according to the projection method that has
      been chosen with the AREA statement.
    
      The procedure should be only be called after a plot frame
      has been opened, e.g. with PLOT_DRIFT_AREA.
    
      Format:
    
      CALL PROJECT_LINE(vector_1, vector_2, vector_3)
    
      Example:
    
      &DRIFT
      Global n=20
      Global nmax=5000
      Call delete_matrices
      Call book_matrix(xbuf,nmax)
      Call book_matrix(ybuf,nmax)
      Call book_matrix(zbuf,nmax)
      Call book_matrix(nbuf,n)
      Call book_matrix(ibuf,n)
      Global i0=1
      For i From 1 Step 1 To n Do
         Global y=4*(i-1)/(n-1)-0.5
         Call drift_electron_3(-0.5,y,1.5,status,time)
         Call get_drift_line(xd,yd,zd,t)
         Call drift_info(`steps`,nd)
         If i0+nd>nmax Then
            Say "Buffer overflow, reducing n to {i-1}."
            Global n=i-1
            Leave
         Endif
         Call book_matrix(ind,nd)
         Global xbuf[i0+ind]=xd
         Global ybuf[i0+ind]=yd
         Global zbuf[i0+ind]=zd
         Global ibuf[i]=i0
         Global nbuf[i]=nd
         Global i0=i0+nd
      Enddo
    
      Do
         Global a
         Global b
         Global c
         Say "Please enter the normal vector of the viewing plane:"
         Parse terminal a b c
         If 'type(a)#`Number`' Then Leave
         area -1.5 -1.5 -1.5 4.5 4.5 4.5 view {a}*x+{b}*y+{c}*z=0 3d
         Call plot_drift_area
         For i From 1 Step 1 To n Do
            Call book_matrix(ind,nbuf[i])
            Global i0=number(ibuf[i])
            Global xd=xbuf[i0+ind]
            Global yd=ybuf[i0+ind]
            Global zd=zbuf[i0+ind]
            Call project_line(xd,yd,zd,`e-drift-line`)
         Enddo
         Call plot_end
      Enddo
    
      (This shows how one can compute a set of drift lines and
      then look at them from various angles - probably more
      interesting for drift lines computed with the MC procedures,
      where the method ensures that the drift lines are the same
      in all projections.)
    

    Additional Information on:

  • vectors

  • PROJECT_MARKERS

      Projects a set of markers according to the projection method
      that has been chosen with the AREA statement.
    
      The procedure should be only be called after a plot frame
      has been opened, e.g. with PLOT_DRIFT_AREA.
    
      Format:
    
      CALL PROJECT_MARKERS(vector_1, vector_2, vector_3)
    
      Example:
    

    Additional Information on:

  • vectors

  • RESHAPE_MATRIX

      RESHAPE_MATRIX is one of two procedures which modify the
      shape of existing matrices. RESHAPE_MATRIX first unpacks
      the matrix in a string of numbers, then fills these numbers
      in a new matrix of the specified dimensions. This
      procedure can therefore be used to change the number
      of dimensions of a matrix.
    
      If the new matrix contains more elements than the old
      matrix did, then the remaining elements are assigned
      the value PAD (the last argument of the procedure).
    
      If the new matrix is smaller than the old matrix, then
      the remaining elements are simply lost.
    
      Format:
    
      CALL RESHAPE_MATRIX(matrix, size_1, size_2, ..., size_n, pad)
    
      Example:
    
      (assume that B is a 3x4 matrix)
      Global a=b[2;]
      Call reshape_matrix(b,4,0.0)
    
      The 2nd row of the matrix B is extracted with the Global
      statement. At this point, A is a 1x4 matrix. In order to
      reduce A to a 4-matrix, RESHAPE_MATRIX is used. The PAD
      argument is compulsory, but its value is not used here.
    

    SOLVE_EQUATION

      (Not yet available)
    

    STORE_SIGNAL

      Copies a 1-dimensional matrix signal to a signal.
    
      The vectors to be stored must have the same length as the
      other signals currently stored. The time vector can not be
      changed with this command.
    
      Format:
    
      CALL STORE_SIGNAL(wire, direct [, cross-induced])
    

    Additional Information on:

  • wire

  • STORE_SUBMATRIX

      Stores a matrix in selected areas of a (larger) matrix.
    
      Both matrices should exist prior to the call and the size of
      the selected area should match the size of the matrix which
      is to be stored.
    
      This procedure is used to process array indexing on the left
      hand side of Global statements. The procedure is not intended
      to be called by the user. Using the Global statement is much
      simpler.
    
      Format:
    
      CALL STORE_SUBMATRIX(ndim, nsel_1, nsel_2, ..., isel_1_1,
           isel_1_2, ..., isel_2_1, isel_2_2, ... , isel_n_1, isel_n_2,
           ref_submatrix, ref_matrix)
    

    STRING_DELETE

      Returns the string with a the part between characters
      istart and iend deleted.
    
      Format:
    
      CALL STRING_DELETE(string, istart, iend, output)
    
      Example:
    
      Call string_delete("abc def ghi",4,8,out)
    

    STRING_INDEX

      Returns the starting position of a substring in a string.
      Returns 0 if the substring is not found within the string.
    
      Format:
    
      CALL STRING_INDEX(string, substring, index)
    
      Example:
    
      Call string_index("abc def","def",pos)
    

    STRING_LENGTH

      Returns the number of characters in a string.
    
      Format:
    
      CALL STRING_LENGTH(string, length)
    
      Example:
    
      CALL STRING_LENGTH("abc",n)
      Say "Length of string is {n} characters."
    

    STRING_LOWER

      Converts a string to lower case.
    
      Format:
    
      CALL STRING_LOWER(string)
    
      Example:
    
      Global str='"ABCDEF"'
      Call string_lower(str)
      Say {str}
    

    STRING_MATCH

      Tells whether a string matches a given pattern. Patterns
      consist of a series of hyphen separated strings in each
      of which one can place a hash sign (#) to indicate the
      point up to which this particular piece of the string can
      be abbreviated.
    
      Format:
    
      CALL STRING_MATCH(string, pattern, match)
    
      Example:
    
      Call string_match("abc-def","ab#cdef-de#fghi-#ghijkl",match)
      If match Then
         Say "The strings match."
      Else
         Say "The strings do not match."
      Endif
    

    STRING_PORTION

      Returns the part of the string that begins at character
      istart and ends at character iend. If the ending position
      precedes the starting position, the string portion that
      is returned is reversed.
    
      Format:
    
      CALL STRING_PORTION(string, istart, iend, portion)
    
      Example:
    
      Call string_portion("abc def ghi",5,7,out)
    

    STRING_UPPER

      Converts a string to upper case.
    
      Format:
    
      CALL STRING_UPPER(string)
    
      Example:
    
      Global str='"abcdef"'
      Call string_upper(str)
      Say {str}
    

    STRING_WORD

      Returns the i'th blank, comma or equal sign delimited
      word from a string.
    
      Format:
    
      CALL STRING_WORD(string, i, word)
    
      Example:
    
      Global str='abc def ghi'
      Call string_words(str,n)
      Say "The string contains {n} words."
      For i From 1 To n Do
          Call string_word(str,i,out)
          Say "Word {i} is {out}."
      Enddo
    

    STRING_WORDS

      Returns the number of words in a string. Words are delimited
      by blanks, commas, colons and equal signs.
    
      Format:
    
      CALL STRING_WORDS(string, n)
    
      Example:
    
      See STRING_WORD
    

    TIME_LOGGING

      Registers the CPU time consumed since the previous time this
      procedure was called, and stores it together with a string that
      serves as annotation.
    
      The entire buffer is printed out at job completion.
    
      Format:
    
      CALL TIME_LOGGING( string )
    
      Example:
    
      Call time_logging(`Until timing test`)
      Global x0=0.5
      Global y0=1.5
      Call plot_cell(0,0,2,2)
      For i From 1 To 100 Do
         Call drift_mc_electron(x0, y0, 0, status, time)
         Call plot_drift)line
      Enddo
      Call time_logging(`MC drifting`)
    
      The TIME_LOGGING routine is called a first time to ensure that
      in the end we will record only the time spent in MC drifting
      will be recorded.
    

    TOWNSEND

      Returns the Townsend coefficient, if available, for a given
      value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).
    
      If the field is specified with vectors, then the result will
      also be a vector. Otherwise the result will be a scalar. It
      is permitted to specify 1 or 2 components of the field with
      scalars and the other(s) with vectors. The result will still
      be a vector in that case.
    
      The electric field should be in V/cm, the Townsend coefficient
      is returned in 1/cm.
    
      Format:
    
      CALL TOWNSEND(ex, ey, ez, townsend)
    

    THRESHOLD_CROSSING

      Returns the times at which a signal crosses a given threshold.
      If both direct and cross-induced signals are available, then
      the threshold crossings are computed for the sum of both.
    
      Format:
    
      CALL THRESHOLD(wire,threshold,option,n,t1 [,t2 [,t3 ...]])
    
      Example:
    
      For i From 1 To 100 Do
         signal
         conv-sig range 0 1000 ...
            transfer-function (5*t/0.01)**5*exp(-5*t/0.01)
         Call threshold_crossing(1,-0.02,`rising,linear`,n,t1,t2)
         Say "Found {n} threshold crossings, 1st at {t1} nsec."
      Enddo
    

    Additional Information on:

  • wire
  • threshold
  • options

  • TRANSVERSE_DIFFUSION

      Returns the transverse diffusion, if available, for a given
      value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).
    
      If the field is specified with vectors, then the result will
      also be a vector. Otherwise the result will be a scalar. It
      is permitted to specify 1 or 2 components of the field with
      scalars and the other(s) with vectors. The result will still
      be a vector in that case.
    
      The electric field should be in V/cm, the diffusion is
      returned in sqrt(cm).
    
      SIGMA_T can be used as a synonym for TRANSVERSE_DIFFUSION.
    
      Format:
    
      CALL TRANSVERSE_DIFFUSION(ex, ey, ez, sigma_t)
    

    WEIGHTING_FIELD

      Returns the field vector with which the drift velocity of a
      moving charge is multiplied in order to get the induced current
      per unit moving charge.
    
      This routine differs from WEIGHTING_FIELD_3 in that it expects
      only the (x,y) part of the location, assuming z=0.
    
      This procedure should be called from within the signal section.
    
      Format:
    
      CALL WEIGHTING_FIELD(x, y, ex, ey, ez, wire [, x_copy] [, y_copy])
    

    Additional Information on:

  • coordinates
  • field
  • wire
  • copy

  • WEIGHTING_FIELD_3

      Returns the field vector with which the drift velocity of a
      moving charge is multiplied in order to get the induced current
      per unit moving charge.
    
      This procedure differs from WEIGHTING_FIELD in that it expects
      an (x,y,z) set of coordinates.
    
      This procedure should be called from within the signal section.
    
      Format:
    
      CALL WEIGHTING_FIELD_3(x, y, z, ex, ey, ez, wire [, x_copy] [, y_copy])
    

    Additional Information on:

  • coordinates
  • field
  • wire
  • copy

  • WRITE_HISTOGRAM

      Writes an histogram to disk, usually for further study by other
      programs, but one can also read the histogram back by Garfield
      to continue the filling process later on. Calling this procedure
      does not interfere with filling of the histogram and an histogram
      can be written to disk before the range has been set (applicable
      for auto range histograms only).
    
      Format:
    
      CALL WRITE_HISTOGRAM(reference, file [, member [, remark]])
    
      Example:
    
      Global chamber=1
    
      (calculation of e.g. arrival time histograms for chamber 1)
    
      Global hfile '"CHAMBER"/string(chamber)/".HIST"'
      Global i=0
      Global exist=True
      Global n=0
      While exist Do
         Global i=i+1
         Call inquire_histogram(reference(i),exist)
         If exist Then
            Call write_histogram(reference(i),hfile)
            Global n=n+1
         Endif
      Enddo
      Say "Have written {n} histograms."
    
      In this example, the input file is assumed to contain a cell
      section that enters the elements for chambers 1, 2, etc depending
      on the setting of the global variable "chamber".
    
      At the end of the run, the user wishes to keep all histograms for
      further examination. The loop in the example writes all histograms
      to a file (hfile) the name of which is CHAMBER1.HIST, CHAMBER2.HIST
      etc. depending on the setting of the global variable "chamber".
    
      All histograms are written to the same file, but they will be
      distinguished by their member names which are defaulted to the
      name of the global variables associated with the histogram.
    
      This example assumes that no histograms have been deleted during
      the run, as it assumes the histograms are numbered from 1 on.
    

    Additional Information on:

  • reference
  • file
  • member

  • WRITE_MATRIX

      WRITE_MATRIX is used to store on disk matrices that take a lot
      of time to compute. These matrices can be retrieved later on
      with the GET_MATRIX procedure.
    
      The Garfield WWW example pages contain a Matlab function that
      reads a file written by WRITE_MATRIX (contributed by Guy Garty):
      http://consult.cern.ch/writeup/garfield/examples/load_garf.m
    
      Format:
    
      CALL WRITE_MATRIX(matrix, file [, member])
    
      Example:
    
      If 'type(global(`ABC`))#`Matrix`' Then
         Call inquire_file(`abc.mat`,exist)
         If exist Then
            Call get_matrix(abc,`abc.mat`,`ABC`)
            Call dimensions(abc,n_dim,dim_abc)
            Global nx=number(dim_abc[1])
            Global ny=number(dim_abc[2])
            Call delete_matrix(dim_abc)
         Else
            Global nx=20
            Global ny=30
            Call book_matrix(abc,nx,ny)
            For i From 1 To nx Do
               For j From 1 To ny Do
                  Global abc[i;j]=sin(i)*exp(j/10)
               Enddo
            Enddo
            Call write_matrix(abc,`abc.mat`)
         Endif
      Endif
    
      First, one checks whether ABC is already in memory. If it is,
      nothing is done. Otherwise, an attempt is made to recuperate
      the matrix from a file. If this doesn't work, then the matrix
      is generated and stored in the file so that next time, the
      matrix can be recuperated from there.
    

    Additional Information on:

  • matrix
  • file
  • member

  • Keyword index. Formatted on 10/11/98.