Go to the first, previous, next, last section, table of contents.


Compiling LSP

Compiling on Unix and Mac OS X

A makefile (called `Makefile') is used to compile LSP. System-dependent parameters and compiler directives are placed in a file `makedef'. `Makefile' calls `madedef'. Sample versions of `makedef' currently exist for

To compile LSP on a particular computer, copy the appropriate file to `makedef' (no extension). Then edit `makedef', inserting the desired compiler directives (see section Compiler Directives) into the PFLAGS definition, e.g.:

# Preprocessor options:
PFLAGS = -DCYL_R_Z -DEXTERNAL_BFIELDS -DKELVIN_DEPOSITION -DMULTI_PROCESS

Now type make. Make calls `Makefile'. If compiler directives are changed, type make new (which is equivalent to make clean followed by make).

`Makefile' may include commands to create documentation. These are referred to as "targets". These targets include

lsp.info:
Creates GNU Info files from the Texinfo file `lsp.txi'
lsp.html:
Creates HTML files from the Texinfo file `lsp.txi'
lsp.dvi:
Runs TeX on `lsp.txi' to produce a DVI file `lsp.dvi'
lsp.ps:
Runs DVIPS on `lsp.dvi' to produce a PostScript file `lsp.ps'
lsppdf.ps:
Runs DVIPS on `lsp.dvi' to produce a PostScript file `lsppdf.ps' suitable for conversion to Adobe PDF format.

The target `alldocs' creates all of the documentation formats listed above.

Compiling on MS Windows

LSP can be compiled with the Microsoft Visual C++ ("VC++") compiler (Version 4 or later). The first time an executable is created, the following steps are required.

  1. Create a "Win32 Console Application" project and import the LSP sources.
  2. Add the XDR library `xdr.lib' to the project files.
  3. Add a path to an include directory containing the subdirectory `rpc' where the files `xdr.h' and `types.h' reside (e.g., Project-Settings-C/C++-Preprocessor-Additional include directories).
  4. Ensure that the preprocessor definition WIN32 is defined (e.g., Project-Settings-C/C++-Preprocessor-Preprocessor definitions). The compiler directives (see section Compiler Directives) may also be set here, or one can use the `lspmake' script.
  5. Add `wsock32.lib' to the default libraries to link against (e.g., Project-Settings-Link-Object/library modules).

The files are ready to be compiled and linked. Once a makefile `lsp.mak' has been generated by VC++ (Project-Export Makefile), compiler directives can be input by either using the Perl script `lspmake.bat' or by typing them into the Project-Settings window. The compiler directives are typed into the file `make.pc' in the source directory, e.g.,

CYL_R_Z EXTERNAL_BFIELDS KELVIN_DEPOSITION MULTI_PROCESS

`Make.pc' is read by `lspmake.bat'.

If the compiler directives have been changed since the last compile, then type lspmake [-d] clean, followed by lspmake [-d], in the source directory. Use the [-d] option for the "Debug" instead of the "Release" version.

[(Note): The clean step is not needed unless compiler directives have changed. In addition, if the VC++ environment variables have not been set at boot time, the file `VCVARS32.BAT' (generated during installation of VC++) should be run before using `lspmake.bat'.]

Error Messages Generated by Incorrect Compilation

Data Type Errors

LSP requires the various data types in C to have specific sizes. Therefore, data types are checked to ensure that the size specification is correct. Often, the problem is with the `long int' data type, which must be 8 bytes. On many systems, the data type having that size is `long long int'. To accomplish this globally, the user must simply define the compiler directive LONG_LONG_INT (see section LONG_LONG_INT).

Unknown Compiler Directive Errors

Incorrect usage of compiler directives may cause an error message. This is usually the result of misspelling one of the standard options in the list of compiler directives specified by the user. An example is:

Compiled Tue Jan 22 10:30:16 MST 2002 on mrcdec.mrcabq.com

Compiler flags: -g -std1

Code options defined by user: -DCYL_R_Z -DCHARGE_DENISTY

Code options defined at compile-time:
    CYLINDRICAL
    CYL_R_Z

 *** Fatal error - Code compiled with unknown option: CHARGE_DENISTY

Simulation abort on Tue Jan 22 10:33:37 2002

Here the user specified CHARGE_DENISTY in the list of defined compiler options where CHARGE_DENSITY was intended.

Incompatible Compiler Directive Errors

There are some combinations of compiler directives which are incompatible. In this case, a compiler error message will appear and the compilation will stop. Some options require another option to be included. Again, if not defined correctly, an error occurs causing the compilation to stop.

Compiler Directives

CAR_ONE

Use 1-D cartesian (x) coordinates.

CAR_X_Y

Use 2-D cartesian (x-y) coordinates.

CAR_X_Z

Use 2-D cartesian (x-z) coordinates.

CARTESIAN

Use 3-D cartesian (x-y-z) coordinates. This is the default coordinate system.

CHARGE_DENSITY

Computes total charge density as a cell quantity. Required if the electrostatic field solver is used (see section STATIC_FIELDS), otherwise optional for diagnostic purposes. Automatically defined if STATIC_FIELDS is defined.

CHARGE_DEPOSITION

Turns on charge deposition on material surfaces.

COLLISIONAL_PLASMA

Enable particle interactions which occur in dense plasmas, such as ionization (see section ionization) and scattering phenomena. The ionization model is applied every ionization_interval timesteps (see section ionization_interval (integer)). The scattering model is applied every scattering_interval timesteps (see section scattering_interval (integer)).

CURRENT_CORRECTION

Turns on the current correction algorithm, for use with either the explicit or the implicit electromagnetic field algorithms.

CURRENTS_OFF

Turns off effect of particle currents on the electromagnetic field solution (for debugging).

CYL_ONE

Use 1-D cylindrical (radial) coordinates.

CYL_R_TH

Use 2-D cylindrical (r-theta) coordinates.

CYL_R_Z

Use 2-D cylindrical (r-z) coordinates.

CYLINDRICAL

Use 3-D cylindrical (r-theta-z) coordinates.

DELAY_BREAKDOWN

Enable specification of a temporal dependence function for modification of emission current after breakdown.

DESORPTION_ON

Enable use of the neutral desorption model.

DIRECT_IMPLICIT

Use the direct-implicit field and particle advance which is an implementation of the fully damped D1 scheme (Ref.[2]). Note that DIRECT_IMPLICIT implies IMPLICIT_FIELDS, as long as STATIC_FIELDS is not defined. See section IMPLICIT_FIELDS.

DOUBLE_PRECISION

Use double precision for all floating-point operations.

DYNAMIC_FIELDS

Solve the electromagnetic fields with one of the dynamic field solvers (explicit or implicit). This option is the default and is necessary only if the fields are pre-calculated with a static field solver prior to advancing the simulation electromagnetically. See section field_initialization_flag (flag).

ENERGY_DEPOSITION

Enables energy deposition on dense material surfaces or in a tenuous gas. This is used in conjunction with certain medium models, specifically the method 1 model of either DENSE or TENUOUS type, and the method 4 model of TENUOUS type only (see section Medium Models Input).

EXACT_IMPLICIT

Solve electromagnetic fields using the "unconditionally stable" ADI procedure as opposed to the conventional ADI scheme, which is iterative in nature and not necessarily stable. This directive can be used as a replacement for the IMPLICIT_FIELDS directive, which invokes the conventional solution when used alone (see section IMPLICIT_FIELDS).

EXTENDED_PARTICLES

Enables the extended particle CIC model in which the size of the particle "cloud" effectively covers two grid cells in each coordinate dimension instead of the usual one cell. The resulting self-force of a particle is reduced by the corresponding reduction in particle density (factor of 2 in 1-D, 4 in 2-D and 8 in 3-D). The key benefit of this treatment is that numerical collisionality is greatly reduced while maintaining good energy conservation. Note that, with the explicit particle-push option, good energy conservation is possible only if the plasma skin depth is adequately resolved.

Warning - this compiler option may not work with complete fidelity under all circumstances. The case that should be avoided is when all of the following are used simultaneously: 1) 3-dimensions, 2) multiple regions, 3) explicit field solution, and 4) particle_forces_option set to PRIMARY for any of the particle species defined in the simulation.

EXTERNAL_BFIELDS

Enables external magnetic fields to be defined by the user, either by functional prescription or from data files, and applied to particle forces. In addition, the definition must be equal to the number of instances of those types of applications if more than one is required. Note that this directive is not required for simple constant values of applied field (see section External Fields Input).

EXTERNAL_EFIELDS

Enables external electric fields to be defined by the user, either by functional prescription or from data files, and applied to particle forces. In addition, the definition must be equal to the number of instances of those types of applications if more than one is required. Note that this directive is not required for simple constant values of applied field (see section External Fields Input).

EXTRA_MOTION

Enables particles to travel more than one cell in a timestep. Usually, when the timestep is limited by the Courant condition, this is not necessary. But in cases where this limitation is not enforced, either by static field solution or by implicit field solution, this directive should be used. One disadvantage of this directive is that at domain boundaries, particles that move more than a single cell beyond that boundary in a timestep will be held back, which may be undesirable. If so, the user may want to use the INTER_DOMAIN_TRACKING directive, which may have slightly less running efficiency (see section INTER_DOMAIN_TRACKING).

FLUID_PHYSICS

Enables electrons or ions to be treated using fluid equations instead of kinetic equations in a collisional plasma. This is used in conjuction with either the COLLISIONAL_PLASMA or the SCATTERING_ON compiler directives. Fluid species are indicated by turning on the fluid_species_flag in the [Particle Species] section of input (see section Particle Species Input).

FLUID_SPECIES=#

Sets the number of fluid species allowed in a simulation. Used in conjunction with the FLUID_PHYSICS compiler directive (see section FLUID_PHYSICS).

Default: 1

FREESPACE_PML

Enables the modeling of freespace with one of the perfectly matched layer (PML) techniques. The two available models are the so-called uniaxial PML, also known as the unsplit version, and the convolutional PML, also known as the complex frequency shifted PML (CFSPML) in its most generalized form. The user must invoke this directive in order to use the PML options under the freespace boundary model (see section Freespace Boundaries).

FRICTIONAL_EFFECTS

Enables frictional (drag) effects between species in a collisional plasma. This is used in conjuction with either the COLLISIONAL_PLASMA or the SCATTERING_ON compiler directives. However, frictional effects can only be used when the direct-implicit algorithm has been invoked (see section DIRECT_IMPLICIT).

FULL_SUSCEPTIBILITY

Uses the full complement of off-diagonal terms of susceptibility for calculating correction currents. Susceptibility is a property of the direct-implicit algorithm (see section DIRECT_IMPLICIT). These additional terms are ordinarily used in the conventional iterative ADI field solution, but not in the "unconditionally stable" version (see section EXACT_IMPLICIT). This directive should be used with caution - it provides a first-order correction only, and is not accurate when fields are changing too rapidly, for example. In such cases it would be advisable to use the iterative ADI solution instead.

IMPLICIT_FIELDS

Uses the ADI field solver. With this option, only fields are treated implicitly. Particles are not. In order to treat particles implicitly, the DIRECT_IMPLICIT option must be defined (see section DIRECT_IMPLICIT).

INTER_DOMAIN_TRACKING

Enables particles to travel more than one cell in a timestep, even across domain boundaries. This can be used in place of the EXTRA_MOTION compiler directive (see section EXTRA_MOTION). The difference between them is that EXTRA_MOTION used alone will hold back particles which, during a timestep, move more than a single cell after crossing a domain boundary, whereas using INTER_DOMAIN_TRACKING will result in unaltered trajectories at a slight expense in running efficiency.

IONIZATION_ON

Enables the ionization model, which is a subset of the collisional plasma model (see section COLLISIONAL_PLASMA). Whenever this directive is used, the compiler directive MUTABLE_SPECIES must also be defined (see section MUTABLE_SPECIES=#).

KELVIN_DEPOSITION

Turns on thermal surface heating in material structures, provided that one of the appropriate medium models is specified for them. This applies to the method 1, method 3, and method 4 medium models (see section Medium Models Input). This thermal deposition can be used for diagnostic purposes, but it is necessary for any particle emission model in which a thermal breakdown is in effect (see section threshold (real)).

LONG_LONG_INT

Defines long long int instead of long int data type for compilers that require that extension in order to get an 8-byte integer.

MAGNETIC_DISPERSION

Required if the ferrite (complex magnetic permeability) model is to be used (see section ferrite).

MAGNETIC_HYSTERESIS

Required if the magnetic hysteresis model is to be used (see section hysteresis).

MAGNETOSTATIC

Solve for magnetostatic fields. This is used in conjunction with the STATIC_FIELDS option (see section STATIC_FIELDS).

MAGNETOSTATIC_FFT2D

Solve for transverse magnetostatic fields using the FFT method, assuming rectangular conducting simulation boundaries. Useful for some paraxial beam simulations.

MAX_RESONANCES=#

Sets the maximum number of resonant frequencies in the ferrite model (see section ferrite).

MAX_SPECIES=#

Sets the maximum number of particle species present in the simulation for the particle scattering model (see section SCATTERING_ON). Also used whenever particle densities by species are required (see section NUMBER_DENSITIES). The default value is 1, but must be set to a larger value when the number of species entered on input is more than one.

Default: 1

MULTI_PROCESS

Enables the use of multiple processes to sub-divide a simulation into domains.

MUTABLE_SPECIES=#

Defines the maximum number of "mutable" species present in the simulation, that is, those that can be ionized to a higher charge state. This directive is used in conjunction with the IONIZATION_ON compiler directive (see section IONIZATION_ON) for the ionization model (see section ionization). To set this properly, count the number of species in the [Particle Species] section which can be ionized to a higher charge state: the value of MUTABLE_SPECIES should be greater than or equal to this number (see section Particle Species Input).

Default: 1

NO_PARTICLES

Eliminates particle-related code from compilation. The advantage of this option is that a smaller executable file can be used for simulations which require no particles.

NUMBER_DENSITIES

Includes number densities for each particle species as cell quantities. This is required for the ion-ion stripping model (see section higherstate), or may be used simply for diagnostic purposes. Whenever this directive is used, the compiler directive MAX_SPECIES must also be defined (see section MAX_SPECIES=#).

PARTICLE_COLLAPSE

Allows use of the particle collapse algorithm, which vastly reduces the number of particles present by combining pairs of particles in the same cell and with similar velocities (see section Particle Collapse Input).

PRIMARY_SPECIES=#

Sets the species number to be used as the primary species for the simulation. For example, the method 2 scattering medium model (see section method 2) is applied only to the primary species and no other.

Default: 1

QUASINEUTRAL_FIELDS

Solve the EM-fields by the quasi-neutral Darwin approximation, that is, with displacement current neglected. This involves modification of the usual Maxwell equations in which Ohm's Law is used instead of Ampere's Law, while still retaining Faraday's Law.

SCATTERING_ON

Enables the scattering model, which is a subset of the collisional plasma model (see section COLLISIONAL_PLASMA). Whenever this directive is used, the compiler directive MAX_SPECIES must also be defined (see section MAX_SPECIES=#).

SPATIAL_FILTER

Invoke the use of diffusive terms to damp light waves spatially in the explicit electromagnetic field equations. See section electric_spatial_filtering_parameter (real), and section magnetic_spatial_filtering_parameter (real).

SPH_ONE

Use 1-D spherical (radial) coordinates.

SPH_R_TH

Use 2-D spherical (r-theta) coordinates.

SPHERICAL

Use 3-D spherical (r-theta-phi) coordinates.

STATIC_FIELDS

Solve the static field equations instead of electromagnetic equations. This directive implies CHARGE_DENSITY as well (see section CHARGE_DENSITY).

STATIC_FIELDS_FFT2D

Solve for transverse electrostatic fields using the FFT method, assuming rectangular conducting simulation boundaries. Useful for some paraxial beam simulations.

STIMULUS_DEPOSITION

Use specific stimulating species for stimulated emission instead of the total charge deposition of all species at the emission surfaces. If more than one stimulating species is required for different instances of the stimulated emission model, the STIMULUS_SPECIES compiler directive must be set to that number (see section STIMULUS_SPECIES=#). Each stimulating species can only be used for a single stimulated model. See also section emission (stimulated).

STIMULUS_SPECIES=#

When stimulated emission requires a specific stimulating species rather than the total charge deposition, STIMULUS_SPECIES should be set to the total number of distinct stimulating species appearing in all stimulated emission input requests (see section emission (stimulated)).

Default: 1

SUBCYCLING_ON

Enable subcycling in the particle advancement whenever the cyclotron frequency becomes high enough to cause inaccuracy in the kinematical calculations.

TEMPORAL_FILTER

Use temporal filtering in the electromagnetic field equations. This is only appropriate under certain conditions. For example, it is never used with any static-fields solution. It can be used with the explicit-fields solution only if time-biasing is not being used. It can also be used with the "exact" version of the implicit-fields solution. See section temporal_filtering_parameter (real).

UNITS_CGS

User units are the standard cgs system of units.

UNITS_MKS

User units are the standard mks system of units.

USE_CONDUCTIVITY

Include conductivities as a cell quantity. This directive is relevant to any of the dynamic field soutions.

USE_OHMIC_TERMS

Include certain fluid-related properties of a plasma such as conductivity and fluid velocity in the cells. These quantities are required for the conductivity model of a gaseous medium (see section Medium Models Input). It is invalid to use this directive with any of the static field solutions (see section STATIC_FIELDS).

USE_PERMEABILITY

Include the magnetic permeability, mu, as a cell quantity. This provides greater flexibility in shaping paramagnetic materials using the medium models (see section Medium Models Input). This directive is required when using paramagnetic materials in the ADI field solver (see section IMPLICIT_FIELDS). It is invalid to use this directive with any of the static field solutions (see section STATIC_FIELDS).

USE_PERMITTIVITY

Include the electric permittivity, epsilon, as a cell quantity. This provides greater flexibility in shaping dielectric materials using the medium models (see section Medium Models Input). This directive is required when using dielectric materials in the ADI field solver (see section IMPLICIT_FIELDS).

USE_PYTHON

Enable use of user-defined functions in Python format in the [Functions] section of input (see section Functions Input).

USE_SUBCELLS

Include the subcell structure as a cell quantity. This enables the use of subgrid modeling, such as the 2-d slope model (see section Subgrid Models Input).

USE_SUBSTRATE

Enable use of the substrate model, which may be restricted by export control (see section Substrate Models Input).

USE_QEOS

Enable use of the qeos model, which may be restricted by export control.

USE_XSEC

Enable use of the ITS (method 4) medium model (see section method 4), which may not be available in all releases of the LSP code. It is restricted to users who have an ITS licence.

VOLUME_WEIGHTING

Use volume weighting, rather than linear, for particle contributions to charge densities and currents when a cylindrical coordinate system is being used.


Go to the first, previous, next, last section, table of contents.