7.34 ion_effects

• type: setup command.
• function: set up for modeling of residual gas ions.
• sequence: must follow run_setup.
• Notes:
  1. The fitting-based methods, i.e., bigaussian, bilorentzian, trigaussian, and trilorentzian, typically show instability when it is not expected and may well have noise challenges that have not been resolved. The poisson method is recommended.
  2. One or more IONEFFECTS elements must be inserted in the lattice. This can be done manually, or using the insert_elements command.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

• pressure_profile — Name of an SDDS file giving the s-dependent gas pressure for various gas species. Column names will be matched to the entries in the SourceName column of the ion_properties file.
• pressure_factor — Factor by which to multiply the pressures given in the pressure_profile.
• long use_local_pressure — If nonzero, use the pressure at the IONEFFECTS element, rather than averaging over a range.
• ion_properties — Name of an SDDS file giving properties of ions. Column names are
  • IonName — String column giving the name of the ion.
  • Mass — Floating-point column giving the ion mass, in AMU.
  • ChargeState — Integer column giving the ion charge state (a positive integer).
  • SourceName — String column giving the name of the source gas for this ion. Alternately, for a multiply ionized molecule (e.g. CO++) one can give a source ion (e.g. CO+). The source ion must also be defined in the ion_properties file.
  • CrossSection — Floating-point column giving the cross section for producing the ion from the source, in Mb.
• beam_output — Possibly incomplete name of an SDDS file to which beam data will be written. Asking for this output can significantly reduce performance, so it should generally be used for testing only.
• beam_output_all_locations — If nonzero, beam_output includes data at the location of all IONEFFECTS elements. By default, only the first element is included.
• ion_density_output — Possibly incomplete name of an SDDS file to which ion density data will be written.
• ion_output_all_locations — If nonzero, ion_density_output includes data at the location of all IONEFFECTS elements. By default, only the first element is included.
• ion_species_output — If nonzero, ion_density_output includes data for each ion species.
• ion_output_interval — The interval in bunches between output of ion data.
• field_calculation_method — By default, the fields are computed on the assumption that the beam and ion distributions are gaussian. This is a good assumption for the beam, but not highly accurate for the ions.

  One can make use of a Poisson solver for the ion fields by setting field_calculation_method to "poisson"; this is presently the recommended method. The Poisson solver uses the FFTW library and is both more stable and faster than the other methods.

  Older alternatives that, though not as good as the Poisson solver, are still more accurate than the gaussian approximation for ion fields are sums of two or three gaussians, or sums of two or three lorentzians, which can be invoked by setting field_calculation_method to "gaussianfit", "bigaussian", "trigaussian", "bilorentzian", or "trilorentzian"; these are collectively referred to as “histogram fitting methods” below. In the gaussian-fit case, the charge distribution is of the form

  (7)

  where G(q,h,σ,c) = hexp-(q - c)²∕(2σ²). In the bigaussian case, the charge distribution is of the form

  (8)

  The charge distribution for the bilorentzian is

  (9)

  where L(q,h,a,c) = h∕(1 + (q - c)²∕a²).

• gaussian_ion_range — If the default field calculation method is used, gives the range (in beam sigma) over which ions are counted, for calculating the ion-beam kicks.
• distribution_fit_target — If the distribution field calculation method is selected, gives the target for the fractional deviation of the fit. Smaller numbers will result in long run times.
• distribution_fit_tolerance — If the distribution field calculation method is selected, gives the tolerance for the fractional deviation of the fit. Smaller numbers will result in long run times but higher likelihood of reaching the target.
• distribution_fit_evaluations, distribution_fit_passes, distribution_fit_restarts — Parameters for the simplex optimizer that performs the distribution fit. Note that in Pelegant, a hybrid simplex method is used, which appears to converge quickly if the default parameters are used.
• fit_residual_type — Residual type for distribution fitting. The default is max-ad-plus-ad-charge, which indicates using the sum of the maximum absolute deviation and the normalized absolute deviation of the total charge, where the latter is computed from difference of the actual total ion charge and the analytical integral of the charge in the summed distributions; this tends to ensure that there are no hidden spikes in the distribution due to overfitting. Other options are sum-ad (sum of normalized absolute deviation), rms-dev (sum of normalized rms deviation), max-ad (maximum normalized absolute deviation), max-ad-plus-rms-dev (sum of maximum normalized absolute deviation and normalized rms deviation), sum-ad-plus-rms-dev, rms-dev-plus-ad-sum, sum-ad-plus-ad-sum, rms-dev-plus-centroid, and rms-dev-plus-ad-charge.
• macro_ions — The number of macro ions to generate per bunch on each turn for which generation is done. The macro ion charge is adjusted according to the cross section and bunch charge. May be overriden by the MACRO_IONS parameter on individual IONEFFECTS elements. If this value is too small, the ion distribution will be noisy, which may result in unreliable results. When using the parallel version, setting macro_ions to 1,000 or higher is not unreasonable.
• symmetrize — If nonzero, ions are emitted in symmetric pairs to ensure that the centroids don’t deviate from the electron beam centroids because of noise. Doubles the number of macro ions that are emitted. Intended primarily for testing purposes.
• generation_interval — The number of bunches between generation of ions. The macro ion charge is adjusted to account for this, so the effective ion charge after many turns is the same. May be overridden with the GENERATION_INTERVAL parameter on individual IONEFFECTS elements. The actual condition for generation of ions is such that the generating bunches vary on each turn. This can be used to effectively reduce macro_ions below 1, to prevent generation of too many macro ions. This will result in noisy histograms and should be used with caution.
• multiple_ionization_interval — The number of bunches between multiple ionization calculations. The macro ion charge is adjusted to account for this, so the effective ion charge after many turns is the same.
• multiple_ionization_energy_peak, multiple_ionization_energy_rms — Specifies the distribution of the energy of multiply-ionized ions in terms of the peak (or centroid) of the distribution and its rms width, in eV.
• ion_span — The transverse half-extent, in meters, of the region within which ions are modeled. Ions moving outside this region are considered lost. May be overriden by the X_SPAN and Y_SPAN parameters on individual IONEFFECTS elements.
• ion_bin_divisor — For histogram fitting methods, the number of ion bins per rms parameter of the electron beam.
• ion_range_multiplier — For histogram fitting methods, used to determine the full span of the ion binning region bins in units of the rms parameter of the ion distribution. The sign of the value determines which algorithm is used. For m < 0, the binning range is σ_ion. For m = 0, the full span of the ion distribution is included; this may result in a very large number of bins beingused to cover a few outlying ions, and is not recommended. For m > 0, the code first finds the approximate range containing the central 80% of the ions, then multiplies by m to get the range used.
• ion_sigma_limit_multiplier — For histogram fitting methods, the minimum value for either of the ion sigmas (for bigaussian) or size parameters (for bilorentizan) in units of the bin size. Use to prevent one of the gaussians or lorentzians from being too delta-function-like.
• ion_histogram_max_bins — Maximum number of ion bins for fitting methods. If this limit is reached, the span of the histograms will be reduced to ensure that the central portion is resolved. If the value is too large, the histograms may be noisy, which will make the fits unreliable. Also, a large value will result in reduced parallel efficiency, as processors must pass around more data.
• ion_histogram_min_per_bin — Minimum number of ions per bin (on average).
• ion_histogram_output, ion_histogram_output_s_start, ion_histogram_output_s_end, ion_histogram_output_interval, ion_histogram_max_bins — Controls for the output of ion histograms when using histogram fitting methods. ion_histogram_output gives the (incomplete) filename. ion_histogram_output_s_start and ion_histogram_output_s_end give limits on the s coordinate of the IONEFFECTS element. ion_histogram_output_interval gives the interval in bunches between output.
• verbosity — Larger values result in more output during running. Used for debugging only.
• ion_poisson_bins — For the Poisson solver option, the number of bins in x and y. For optimal speed, these should by the multiple of small primes.
• ion_poisson_span — If nonzero, the Poisson equation is solved over this range (rather than the full ion_span).

The user is strongly advised to study the ion histograms by using the ion_histogram_output parameter to request this data. The histograms should not be excessively noisy. The data also includes the fits, which should be close to the data. (For “gaussian” mode, this is generally not possible.) A sample command to examine the histograms and fits for the y plane (generally the most difficult) is

The Poisson solver option makes use of the FFTW library (http://www.fftw.org/). This library must be installed for the Poisson solver to work. If ion_poisson_span is not given, the Poisson equation is solved over the full ion_span.