diff --git a/doc/Manual.html b/doc/Manual.html index 98558dd568..d5d8ee5714 100644 --- a/doc/Manual.html +++ b/doc/Manual.html @@ -59,13 +59,17 @@ we can improve the LAMMPS documentation.
2.2 Making LAMMPS
- 2.3 Running LAMMPS + 2.3 Making LAMMPS with optional packages
- 2.4 Command-line options + 2.4 Building LAMMPS as a library
- 2.5 Screen output + 2.5 Running LAMMPS
- 2.6 Tips for users of previous versions + 2.6 Command-line options +
+ 2.7 Screen output +
+ 2.8 Tips for users of previous versions
  • Commands @@ -182,6 +186,10 @@ we can improve the LAMMPS documentation. + + + + diff --git a/doc/Manual.txt b/doc/Manual.txt index 2606c35138..c5d140d9b5 100644 --- a/doc/Manual.txt +++ b/doc/Manual.txt @@ -47,10 +47,12 @@ we can improve the LAMMPS documentation. "Getting started"_Section_start.html :l 2.1 "What's in the LAMMPS distribution"_2_1 :ulb,b 2.2 "Making LAMMPS"_2_2 :b - 2.3 "Running LAMMPS"_2_3 :b - 2.4 "Command-line options"_2_4 :b - 2.5 "Screen output"_2_5 :b - 2.6 "Tips for users of previous versions"_2_6 :ule,b + 2.3 "Making LAMMPS with optional packages"_#2_3 :b + 2.4 "Building LAMMPS as a library"_#2_4 :b + 2.5 "Running LAMMPS"_2_5 :b + 2.6 "Command-line options"_2_6 :b + 2.7 "Screen output"_2_7 :b + 2.8 "Tips for users of previous versions"_2_8 :ule,b "Commands"_Section_commands.html :l 3.1 "LAMMPS input script"_3_1 :ulb,b 3.2 "Parsing rules"_3_2 :b @@ -93,6 +95,8 @@ we can improve the LAMMPS documentation. :link(2_4,Section_start.html#2_4) :link(2_5,Section_start.html#2_5) :link(2_6,Section_start.html#2_6) +:link(2_7,Section_start.html#2_7) +:link(2_8,Section_start.html#2_8) :link(3_1,Section_commands.html#3_1) :link(3_2,Section_commands.html#3_2) diff --git a/doc/Section_commands.html b/doc/Section_commands.html index ba27ef7aaa..beddd7c494 100644 --- a/doc/Section_commands.html +++ b/doc/Section_commands.html @@ -181,7 +181,6 @@ set in the read-in files): pair_coeff, special_bonds.

    Various simulation parameters are set by these commands: -temperature, temp_modify, neighbor, neigh_modify, group, timestep, reset_timestep, run_style, @@ -190,8 +189,13 @@ set in the read-in files): pair_coeff,

    Fixes impose a variety of boundary conditions, time integration, and diagnostic options. The fix command comes in many flavors.

    -

    Output options are set by these commands: thermo, -dump, restart. +

    Various computations can be specified for execution during a +simulation using the compute, +compute_modify, and variable +commands. +

    +

    Output options are set by the thermo, dump, +and restart commands.

    (4) Run a simulation

    @@ -245,14 +249,17 @@ in the command's documentation. min_modify, min_style, neigh_modify, neighbor, reset_timestep, run_style, -set, temp_modify, -temperature, timestep, -velocity +set, timestep, velocity

    Fixes:

    fix, fix_modify, unfix

    +

    Computes: +

    +

    compute, compute_modify, +uncompute +

    Output:

    dump, dump_modify, @@ -288,83 +295,109 @@ in the command's documentation.

    - - - - - - - - - - - + + + + + + + + + +
    angle_coeffangle_styleatom_modifyatom_stylebond_coeffbond_style
    boundaryclearcreate_atomscreate_boxdelete_atomsdelete_bonds
    dielectricdihedral_coeffdihedral_styledimensiondipoledisplace_atoms
    dumpdump_modifyechofixfix_modifygroup
    improper_coeffimproper_styleincludejumpkspace_modifykspace_style
    labellatticelogmassminimizemin_modify
    min_styleneigh_modifyneighbornewtonnextpair_coeff
    pair_modifypair_stylepair_writeprintprocessorsread_data
    read_restartregionreplicatereset_timesteprestartrun
    run_stylesetshellspecial_bondstemp_modifytemper
    temperaturethermothermo_modifythermo_styletimestepundump
    unfixunitsvariablevelocitywrite_restart +
    boundaryclearcomputecompute_modifycreate_atomscreate_box
    delete_atomsdelete_bondsdielectricdihedral_coeffdihedral_styledimension
    dipoledisplace_atomsdumpdump_modifyechofix
    fix_modifygroupimproper_coeffimproper_styleincludejump
    kspace_modifykspace_stylelabellatticelogmass
    minimizemin_modifymin_styleneigh_modifyneighbornewton
    nextpair_coeffpair_modifypair_stylepair_writeprint
    processorsread_dataread_restartregionreplicatereset_timestep
    restartrunrun_stylesetshellspecial_bonds
    temperthermothermo_modifythermo_styletimestepuncompute
    undumpunfixunitsvariablevelocitywrite_restart
    -

    Fix styles. See the fix command for one-line descriptions -or click on the command itself for a full description: -

    -
    - - - - - - - -
    fix addforcefix aveforcefix comfix depositfix dragfix efield
    fix enforce2dfix freezefix gran/diagfix gravityfix gyrationfix indent
    fix langevinfix lineforcefix msdfix momentumfix nphfix npt
    fix nvefix nve/granfix nvtfix orient/fccfix planeforcefix poems
    fix pourfix printfix rdffix recenterfix rigidfix setforce
    fix shakefix springfix spring/rgfix spring/selffix temp/rescalefix tmd
    fix uniaxialfix vcmfix viscousfix volume/rescalefix wall/granfix wall/lj93
    fix wall/lj126fix wall/reflectfix wiggle -
    +
    -

    Pair styles. See the pair_style command for an -overview of pair potentials. Click on the style itself for a full +

    Fix commands. See the fix command for one-line +descriptions of each style or click on the style itself for a full description:

    - - - - - - - - + + + + +
    nonehybridbuckbuck/coul/cut
    buck/coul/longdpdeameam/alloy
    eam/fsgran/hertziangran/historygran/no_history
    lj/charmm/coul/charmmlj/charmm/coul/charmm/implicitlj/charmm/coul/longlj/class2
    lj/class2/coul/cutlj/class2/coul/longlj/cutlj/cut/coul/cut
    lj/cut/coul/debyelj/cut/coul/longlj/cut/coul/long/tip4plj/expand
    lj/smoothmeammorsesoft
    swtabletersoffyukawa +
    addforceaveforcecomdepositdragefieldenforce2dfreeze
    gran/diaggravitygyrationindentlangevinlineforcemsdmomentum
    nphnptnvenve/grannvtorient/fccplaneforcepoems
    pourprintrdfrecenterrigidsetforceshakespring
    spring/rgspring/selftemp/rescaletmduniaxialvcmviscousvolume/rescale
    wall/granwall/lj93wall/lj126wall/reflectwiggle
    -

    Bond styles. See the bond_style command for an -overview of bond potentials. Click on the style itself for a full +


    + +

    Compute commands. See the compute command for one-line +descriptions of each style or click on the style itself for a full description:

    - - - +
    nonehybridclass2fene
    fene/expandharmonicmorsenonlinear
    quartic +
    centro/atomepair/atometotal/atomke/atompressurerotate/dipole
    rotate/granstress/atomtemptemp/partialtemp/ramptemp/region
    -

    Angle styles. See the angle_style command for an -overview of angle potentials. Click on the style itself for a full +


    + +

    Pair_style potentials. See the pair_style command +for an overview of pair potentials. Click on the style itself for a +full description: +

    +
    + + + + + + + + + +
    nonehybridbuckbuck/coul/cut
    buck/coul/longdpdeameam/opt
    eam/alloyeam/alloy/opteam/fseam/fs/opt
    gran/hertziangran/historygran/no_historylj/charmm/coul/charmm
    lj/charmm/coul/charmm/implicitlj/charmm/coul/longlj/charmm/coul/long/optlj/class2
    lj/class2/coul/cutlj/class2/coul/longlj/cutlj/cut/opt
    lj/cut/coul/cutlj/cut/coul/debyelj/cut/coul/longlj/cut/coul/long/tip4p
    lj/expandlj/smoothmeammorse
    morse/optsoftswtable
    tersoffyukawa +
    + +
    + +

    Bond_style potentials. See the bond_style command +for an overview of bond potentials. Click on the style itself for a +full description: +

    +
    + + +
    nonehybridclass2fene
    fene/expandharmonicmorsenonlinear
    quartic +
    + +
    + +

    Angle_style potentials. See the angle_style +command for an overview of angle potentials. Click on the style +itself for a full description: +

    +
    + +
    nonehybridcharmmclass2
    cosinecosine/squaredharmonic +
    + +
    + +

    Dihedral_style potentials. See the +dihedral_style command for an overview of +dihedral potentials. Click on the style itself for a full description:

    - - +
    nonehybridcharmmclass2cosinecosine/squared
    harmonic +
    nonehybridcharmmclass2
    harmonichelixmulti/harmonicopls
    -

    Dihedral styles. See the dihedral_style command -for an overview of dihedral potentials. Click on the style itself for -a full description: -

    -
    - -
    nonehybridcharmmclass2harmonichelixmulti/harmonic
    opls -
    +
    -

    Improper styles. See the improper_style command for an -overview of improper potentials. Click on the style itself for a full +

    Improper_style potentials. See the +improper_style command for an overview of +improper potentials. Click on the style itself for a full description:

    - - +
    nonehybridclass2cvff
    harmonic +
    nonehybridclass2cvff
    harmonic
    diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt index f2eb2a32bb..7c2028efcd 100644 --- a/doc/Section_commands.txt +++ b/doc/Section_commands.txt @@ -178,7 +178,6 @@ set in the read-in files): "pair_coeff"_pair_coeff.html, "special_bonds"_special_bonds.html. Various simulation parameters are set by these commands: -"temperature"_temperature.html, "temp_modify"_temp_modify.html, "neighbor"_neighbor.html, "neigh_modify"_neigh_modify.html, "group"_group.html, "timestep"_timestep.html, "reset_timestep"_reset_timestep.html, "run_style"_run_style.html, @@ -187,8 +186,13 @@ Various simulation parameters are set by these commands: Fixes impose a variety of boundary conditions, time integration, and diagnostic options. The "fix"_fix.html command comes in many flavors. -Output options are set by these commands: "thermo"_thermo.html, -"dump"_dump.html, "restart"_restart.html. +Various computations can be specified for execution during a +simulation using the "compute"_compute.html, +"compute_modify"_compute_modify.html, and "variable"_variable.html +commands. + +Output options are set by the "thermo"_thermo.html, "dump"_dump.html, +and "restart"_restart.html commands. (4) Run a simulation @@ -242,14 +246,17 @@ Settings: "min_modify"_min_modify.html, "min_style"_min_style.html, "neigh_modify"_neigh_modify.html, "neighbor"_neighbor.html, "reset_timestep"_reset_timestep.html, "run_style"_run_style.html, -"set"_set.html, "temp_modify"_temp_modify.html, -"temperature"_temperature.html, "timestep"_timestep.html, -"velocity"_velocity.html +"set"_set.html, "timestep"_timestep.html, "velocity"_velocity.html Fixes: "fix"_fix.html, "fix_modify"_fix_modify.html, "unfix"_unfix.html +Computes: + +"compute"_compute.html, "compute_modify"_compute_modify.html, +"uncompute"_uncompute.html + Output: "dump"_dump.html, "dump_modify"_dump_modify.html, @@ -291,6 +298,8 @@ in the command's documentation. "bond_style"_bond_style.html, "boundary"_boundary.html, "clear"_clear.html, +"compute"_compute.html, +"compute_modify"_compute_modify.html, "create_atoms"_create_atoms.html, "create_box"_create_box.html, "delete_atoms"_delete_atoms.html, @@ -341,13 +350,12 @@ in the command's documentation. "set"_set.html, "shell"_shell.html, "special_bonds"_special_bonds.html, -"temp_modify"_temp_modify.html, "temper"_temper.html, -"temperature"_temperature.html, "thermo"_thermo.html, "thermo_modify"_thermo_modify.html, "thermo_style"_thermo_style.html, "timestep"_timestep.html, +"uncompute"_uncompute.html, "undump"_undump.html, "unfix"_unfix.html, "units"_units.html, @@ -355,137 +363,177 @@ in the command's documentation. "velocity"_velocity.html, "write_restart"_write_restart.html :tb(c=6,ea=c) -Fix styles. See the "fix"_fix.html command for one-line descriptions -or click on the command itself for a full description: +:line -"fix addforce"_fix_addforce.html, -"fix aveforce"_fix_aveforce.html, -"fix com"_fix_com.html, -"fix deposit"_fix_deposit.html, -"fix drag"_fix_drag.html, -"fix efield"_fix_efield.html, -"fix enforce2d"_fix_enforce2d.html, -"fix freeze"_fix_freeze.html, -"fix gran/diag"_fix_gran_diag.html, -"fix gravity"_fix_gravity.html, -"fix gyration"_fix_gyration.html, -"fix indent"_fix_indent.html, -"fix langevin"_fix_langevin.html, -"fix lineforce"_fix_lineforce.html, -"fix msd"_fix_msd.html, -"fix momentum"_fix_momentum.html, -"fix nph"_fix_nph.html, -"fix npt"_fix_npt.html, -"fix nve"_fix_nve.html, -"fix nve/gran"_fix_nve_gran.html, -"fix nvt"_fix_nvt.html, -"fix orient/fcc"_fix_orient_fcc.html, -"fix planeforce"_fix_planeforce.html, -"fix poems"_fix_poems.html, -"fix pour"_fix_pour.html, -"fix print"_fix_print.html, -"fix rdf"_fix_rdf.html, -"fix recenter"_fix_recenter.html, -"fix rigid"_fix_rigid.html, -"fix setforce"_fix_setforce.html, -"fix shake"_fix_shake.html, -"fix spring"_fix_spring.html, -"fix spring/rg"_fix_spring_rg.html, -"fix spring/self"_fix_spring_self.html, -"fix temp/rescale"_fix_temp_rescale.html, -"fix tmd"_fix_tmd.html, -"fix uniaxial"_fix_uniaxial.html, -"fix vcm"_fix_vcm.html, -"fix viscous"_fix_viscous.html, -"fix volume/rescale"_fix_volume_rescale.html, -"fix wall/gran"_fix_wall_gran.html, -"fix wall/lj93"_fix_wall_lj93.html, -"fix wall/lj126"_fix_wall_lj126.html, -"fix wall/reflect"_fix_wall_reflect.html, -"fix wiggle"_fix_wiggle.html :tb(c=6,ea=c) - -Pair styles. See the "pair_style"_pair_style.html command for an -overview of pair potentials. Click on the style itself for a full +Fix commands. See the "fix"_fix.html command for one-line +descriptions of each style or click on the style itself for a full description: -"none"_pair_style_none.html, -"hybrid"_pair_style_hybrid.html, -"buck"_pair_style_buck.html, -"buck/coul/cut"_pair_style_buck.html, -"buck/coul/long"_pair_style_buck.html, -"dpd"_pair_style_dpd.html, -"eam"_pair_style_eam.html, -"eam/alloy"_pair_style_eam.html, -"eam/fs"_pair_style_eam.html, -"gran/hertzian"_pair_style_gran.html, -"gran/history"_pair_style_gran.html, -"gran/no_history"_pair_style_gran.html, -"lj/charmm/coul/charmm"_pair_style_charmm.html, -"lj/charmm/coul/charmm/implicit"_pair_style_charmm.html, -"lj/charmm/coul/long"_pair_style_charmm.html, -"lj/class2"_pair_style_class2.html, -"lj/class2/coul/cut"_pair_style_class2.html, -"lj/class2/coul/long"_pair_style_class2.html, -"lj/cut"_pair_style_lj.html, -"lj/cut/coul/cut"_pair_style_lj.html, -"lj/cut/coul/debye"_pair_style_lj.html, -"lj/cut/coul/long"_pair_style_lj.html, -"lj/cut/coul/long/tip4p"_pair_style_lj.html, -"lj/expand"_pair_style_lj_expand.html, -"lj/smooth"_pair_style_lj_smooth.html, -"meam"_pair_style_meam.html, -"morse"_pair_style_morse.html, -"soft"_pair_style_soft.html, -"sw"_pair_style_sw.html, -"table"_pair_style_table.html, -"tersoff"_pair_style_tersoff.html, -"yukawa"_pair_style_yukawa.html :tb(c=4,ea=c) +"addforce"_fix_addforce.html, +"aveforce"_fix_aveforce.html, +"com"_fix_com.html, +"deposit"_fix_deposit.html, +"drag"_fix_drag.html, +"efield"_fix_efield.html, +"enforce2d"_fix_enforce2d.html, +"freeze"_fix_freeze.html, +"gran/diag"_fix_gran_diag.html, +"gravity"_fix_gravity.html, +"gyration"_fix_gyration.html, +"indent"_fix_indent.html, +"langevin"_fix_langevin.html, +"lineforce"_fix_lineforce.html, +"msd"_fix_msd.html, +"momentum"_fix_momentum.html, +"nph"_fix_nph.html, +"npt"_fix_npt.html, +"nve"_fix_nve.html, +"nve/gran"_fix_nve_gran.html, +"nvt"_fix_nvt.html, +"orient/fcc"_fix_orient_fcc.html, +"planeforce"_fix_planeforce.html, +"poems"_fix_poems.html, +"pour"_fix_pour.html, +"print"_fix_print.html, +"rdf"_fix_rdf.html, +"recenter"_fix_recenter.html, +"rigid"_fix_rigid.html, +"setforce"_fix_setforce.html, +"shake"_fix_shake.html, +"spring"_fix_spring.html, +"spring/rg"_fix_spring_rg.html, +"spring/self"_fix_spring_self.html, +"temp/rescale"_fix_temp_rescale.html, +"tmd"_fix_tmd.html, +"uniaxial"_fix_uniaxial.html, +"vcm"_fix_vcm.html, +"viscous"_fix_viscous.html, +"volume/rescale"_fix_volume_rescale.html, +"wall/gran"_fix_wall_gran.html, +"wall/lj93"_fix_wall_lj93.html, +"wall/lj126"_fix_wall_lj126.html, +"wall/reflect"_fix_wall_reflect.html, +"wiggle"_fix_wiggle.html :tb(c=8,ea=c) -Bond styles. See the "bond_style"_bond_style.html command for an -overview of bond potentials. Click on the style itself for a full +:line + +Compute commands. See the "compute"_compute.html command for one-line +descriptions of each style or click on the style itself for a full description: -"none"_bond_style_none.html, -"hybrid"_bond_style_hybrid.html, -"class2"_bond_style_class2.html, -"fene"_bond_style_fene.html, -"fene/expand"_bond_style_fene_expand.html, -"harmonic"_bond_style_harmonic.html, -"morse"_bond_style_morse.html, -"nonlinear"_bond_style_nonlinear.html, -"quartic"_bond_style_quartic.html :tb(c=4,ea=c,w=100) +"centro/atom"_compute_centro_atom.html, +"epair/atom"_compute_epair_atom.html, +"etotal/atom"_compute_etotal_atom.html, +"ke/atom"_compute_ke_atom.html, +"pressure"_compute_pressure.html, +"rotate/dipole"_compute_rotate_dipole.html, +"rotate/gran"_compute_rotate_gran.html, +"stress/atom"_compute_stress_atom.html, +"temp"_compute_temp.html, +"temp/partial"_compute_temp_partial.html, +"temp/ramp"_compute_temp_ramp.html, +"temp/region"_compute_temp_region.html :tb(c=6,ea=c) -Angle styles. See the "angle_style"_angle_style.html command for an -overview of angle potentials. Click on the style itself for a full +:line + +Pair_style potentials. See the "pair_style"_pair_style.html command +for an overview of pair potentials. Click on the style itself for a +full description: + +"none"_pair_none.html, +"hybrid"_pair_hybrid.html, +"buck"_pair_buck.html, +"buck/coul/cut"_pair_buck.html, +"buck/coul/long"_pair_buck.html, +"dpd"_pair_dpd.html, +"eam"_pair_eam.html, +"eam/opt"_pair_eam.html, +"eam/alloy"_pair_eam.html, +"eam/alloy/opt"_pair_eam.html, +"eam/fs"_pair_eam.html, +"eam/fs/opt"_pair_eam.html, +"gran/hertzian"_pair_gran.html, +"gran/history"_pair_gran.html, +"gran/no_history"_pair_gran.html, +"lj/charmm/coul/charmm"_pair_charmm.html, +"lj/charmm/coul/charmm/implicit"_pair_charmm.html, +"lj/charmm/coul/long"_pair_charmm.html, +"lj/charmm/coul/long/opt"_pair_charmm.html, +"lj/class2"_pair_class2.html, +"lj/class2/coul/cut"_pair_class2.html, +"lj/class2/coul/long"_pair_class2.html, +"lj/cut"_pair_lj.html, +"lj/cut/opt"_pair_lj.html, +"lj/cut/coul/cut"_pair_lj.html, +"lj/cut/coul/debye"_pair_lj.html, +"lj/cut/coul/long"_pair_lj.html, +"lj/cut/coul/long/tip4p"_pair_lj.html, +"lj/expand"_pair_lj_expand.html, +"lj/smooth"_pair_lj_smooth.html, +"meam"_pair_meam.html, +"morse"_pair_morse.html, +"morse/opt"_pair_morse.html, +"soft"_pair_soft.html, +"sw"_pair_sw.html, +"table"_pair_table.html, +"tersoff"_pair_tersoff.html, +"yukawa"_pair_yukawa.html :tb(c=4,ea=c) + +:line + +Bond_style potentials. See the "bond_style"_bond_style.html command +for an overview of bond potentials. Click on the style itself for a +full description: + +"none"_bond_none.html, +"hybrid"_bond_hybrid.html, +"class2"_bond_class2.html, +"fene"_bond_fene.html, +"fene/expand"_bond_fene_expand.html, +"harmonic"_bond_harmonic.html, +"morse"_bond_morse.html, +"nonlinear"_bond_nonlinear.html, +"quartic"_bond_quartic.html :tb(c=4,ea=c,w=100) + +:line + +Angle_style potentials. See the "angle_style"_angle_style.html +command for an overview of angle potentials. Click on the style +itself for a full description: + +"none"_angle_none.html, +"hybrid"_angle_hybrid.html, +"charmm"_angle_charmm.html, +"class2"_angle_class2.html, +"cosine"_angle_cosine.html, +"cosine/squared"_angle_cosine_squared.html, +"harmonic"_angle_harmonic.html :tb(c=4,ea=c,w=100) + +:line + +Dihedral_style potentials. See the +"dihedral_style"_dihedral_style.html command for an overview of +dihedral potentials. Click on the style itself for a full description: -"none"_angle_style_none.html, -"hybrid"_angle_style_hybrid.html, -"charmm"_angle_style_charmm.html, -"class2"_angle_style_class2.html, -"cosine"_angle_style_cosine.html, -"cosine/squared"_angle_style_cosine_squared.html, -"harmonic"_angle_style_harmonic.html :tb(c=6,ea=c,w=100) +"none"_dihedral_none.html, +"hybrid"_dihedral_hybrid.html, +"charmm"_dihedral_charmm.html, +"class2"_dihedral_class2.html, +"harmonic"_dihedral_harmonic.html, +"helix"_dihedral_helix.html, +"multi/harmonic"_dihedral_multi_harmonic.html, +"opls"_dihedral_opls.html :tb(c=4,ea=c,w=100) -Dihedral styles. See the "dihedral_style"_dihedral_style.html command -for an overview of dihedral potentials. Click on the style itself for -a full description: +:line -"none"_dihedral_style_none.html, -"hybrid"_dihedral_style_hybrid.html, -"charmm"_dihedral_style_charmm.html, -"class2"_dihedral_style_class2.html, -"harmonic"_dihedral_style_harmonic.html, -"helix"_dihedral_style_helix.html, -"multi/harmonic"_dihedral_style_multi_harmonic.html, -"opls"_dihedral_style_opls.html :tb(c=7,ea=c,w=100) - -Improper styles. See the "improper_style"_improper_style.html command for an -overview of improper potentials. Click on the style itself for a full +Improper_style potentials. See the +"improper_style"_improper_style.html command for an overview of +improper potentials. Click on the style itself for a full description: -"none"_improper_style_none.html, -"hybrid"_improper_style_hybrid.html, -"class2"_improper_style_class2.html, -"cvff"_improper_style_cvff.html, -"harmonic"_improper_style_harmonic.html :tb(c=4,ea=c,w=100) +"none"_improper_none.html, +"hybrid"_improper_hybrid.html, +"class2"_improper_class2.html, +"cvff"_improper_cvff.html, +"harmonic"_improper_harmonic.html :tb(c=4,ea=c,w=100) diff --git a/doc/Section_errors.html b/doc/Section_errors.html index 9add21922f..a27f2b6065 100644 --- a/doc/Section_errors.html +++ b/doc/Section_errors.html @@ -1,5 +1,7 @@ -
    Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands - Next Section +
    Previous Section - LAMMPS WWW Site - +LAMMPS Documentation - LAMMPS Commands - Next +Section
    diff --git a/doc/Section_errors.txt b/doc/Section_errors.txt index f49e855ea7..991c37036b 100644 --- a/doc/Section_errors.txt +++ b/doc/Section_errors.txt @@ -1,4 +1,6 @@ -"Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_history.html :c +"Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Section_history.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/Section_howto.html b/doc/Section_howto.html index c53aa907f9..0f8ae2da8e 100644 --- a/doc/Section_howto.html +++ b/doc/Section_howto.html @@ -263,7 +263,7 @@ jump in.polymer

    All of the above examples work whether you are running on 1 or multiple processors, but assumed you are running LAMMPS on a single partition of processors. LAMMPS can be run on multiple partitions via -the "-partition" command-line switch as described in this +the "-partition" command-line switch as described in this section of the manual.

    In the last 2 examples, if LAMMPS were run on 3 partitions, the same @@ -287,7 +287,7 @@ simulation are run at different temperatures on different sets of processors, and Monte Carlo temperature swaps are performed between pairs of copies.

    -

    Use the -procs and -in command-line switches +

    Use the -procs and -in command-line switches to launch LAMMPS on multiple partitions.

    In your input script, define a set of temperatures, one for each @@ -409,10 +409,12 @@ This site M is located at a fixed distance away from the oxygen along the bisector of the HOH bond angle. A bond style of harmonic and an angle style of harmonic or charmm should also be used.

    -

    Two different four-point models (cutoff and long-range Coulombics) can -be implemented using LAMMPS pair styles with tip4p in their style -name. For both models, the bond lengths and bond angles should be -held fixed using the fix shake command. +

    Currently, only a four-point model for long-range Coulombics is +implemented via the LAMMPS pair style +lj/cut/coul/long/tip4p. We plan to add a cutoff +version in the future. For both models, the bond lengths and bond +angles should be held fixed using the fix shake +command.

    These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP4P model with a cutoff @@ -510,16 +512,16 @@ a new fix to LAMMPS.

    (2) Define a new LAMMPS command that calls the other code. This is conceptually similar to method (1), but in this case LAMMPS and the -other code are on a more equal footing. Note that now the other -code is not called during the timesteps of a LAMMPS run, but between +other code are on a more equal footing. Note that now the other code +is not called during the timestepping of a LAMMPS run, but between runs. The LAMMPS input script can be used to alternate LAMMPS runs with calls to the other code, invoked via the new command. The run command facilitates this with its every option, which makes it easy to run a few steps, invoke the command, run a few steps, invoke the command, etc.

    -

    In this scenario, the other code can be a library, called by the -command, or it could be a stand-alone code, invoked by a system() call +

    In this scenario, the other code can be called as a library, as in +(1), or it could be a stand-alone code, invoked by a system() call made by the command (assuming your parallel machine allows one or more processors to start up another program). In the latter case the stand-alone code could communicate with LAMMPS thru files that the @@ -535,49 +537,55 @@ Again, the run command has options that allow it to be invoked with minimal overhead (no setup or clean-up) if you wish to do multiple short runs, driven by another program.

    -

    This section of the documentation describes -how to build LAMMPS as a library. Once this is done, you can interface -with LAMMPS either via C++, C, or Fortran (or any other language that -supports a vanilla C-like interface, e.g. a scripting language). For -example, from C++ you could create an "instance" of LAMMPS, and -initialize it, pass it an input script to process, or execute +

    This section of the documentation describes +how to build LAMMPS as a library. Once this is done, you can +interface with LAMMPS either via C++, C, or Fortran (or any other +language that supports a vanilla C-like interface, e.g. a scripting +language). For example, from C++ you could create one (or more) +"instances" of LAMMPS, pass it an input script to process, or execute individual commands, all by invoking the correct class methods in -LAMMPS. From C or Fortran you would make function calls to do the -same things. Library.cpp and library.h contain such a C interface -that illustrates this with the functions: +LAMMPS. From C or Fortran you can make function calls to do the same +things. Library.cpp and library.h contain such a C interface with the +functions:

    -
    void lammps_open(int, char **, MPI_Comm);
    -void lammps_close();
    -void lammps_file(char *);
    -char *lammps_command(char *); 
    +
    void lammps_open(int, char **, MPI_Comm, void **);
    +void lammps_close(void *);
    +void lammps_file(void *, char *);
    +char *lammps_command(doivd *, char *); 
     
    -

    The functions contain the C++ code you would need to put in a C++ -application that was invoking LAMMPS directly. +

    The functions contain C++ code you could write in a C++ application +that was invoking LAMMPS directly. Note that LAMMPS classes are +defined wihin a LAMMPS namespace (LAMMPS_NS) if you use them +from another C++ application.

    Two of the routines in library.cpp are of particular note. The lammps_open() function initiates LAMMPS and takes an MPI communicator -as an argument. LAMMPS will run on the set of processors in the -communicator. This means the calling code can run LAMMPS on all or a -subset of processors. For example, a wrapper script might decide to -alternate between LAMMPS and another code, allowing them both to run -on all the processors. Or it might allocate half the processors to -LAMMPS and half to the other code and run both codes simultaneously -before syncing them up periodically. +as an argument. It returns a pointer to a LAMMPS "object". As with +C++, the lammps_open() function can be called mutliple times, to +create multiple instances of LAMMPS.

    -

    Library.cpp also contains a lammps_command() function to which the -caller passes a single LAMMPS command (a string). Thus the calling -code can read or generate a series of LAMMPS commands (e.g. an input -script) one line at a time and pass it thru the library interface to -setup a problem and then run it. +

    LAMMPS will run on the set of processors in the communicator. This +means the calling code can run LAMMPS on all or a subset of +processors. For example, a wrapper script might decide to alternate +between LAMMPS and another code, allowing them both to run on all the +processors. Or it might allocate half the processors to LAMMPS and +half to the other code and run both codes simultaneously before +syncing them up periodically.

    -

    A few other sample routines are included in library.cpp, but the key -idea is that you can write any routines you wish to define an +

    Library.cpp contains a lammps_command() function to which the caller +passes a single LAMMPS command (a string). Thus the calling code can +read or generate a series of LAMMPS commands (e.g. an input script) +one line at a time and pass it thru the library interface to setup a +problem and then run it. +

    +

    A few other sample functions are included in library.cpp, but the key +idea is that you can write any functions you wish to define an interface for how your code talks to LAMMPS and add them to library.cpp and library.h. The routines you add can access any LAMMPS -data. The umbrella.cpp code in examples/couple is a simple example of -how a stand-alone code can link LAMMPS as a library, run LAMMPS on a -subset of processors, grab data from LAMMPS, change it, and put it -back into LAMMPS. +data. The examples/couple directory has example C++ and C codes which +show how a stand-alone code can link LAMMPS as a library, run LAMMPS +on a subset of processors, grab data from LAMMPS, change it, and put +it back into LAMMPS.


    diff --git a/doc/Section_howto.txt b/doc/Section_howto.txt index a65c4163c4..009593e1a6 100644 --- a/doc/Section_howto.txt +++ b/doc/Section_howto.txt @@ -260,7 +260,7 @@ All of the above examples work whether you are running on 1 or multiple processors, but assumed you are running LAMMPS on a single partition of processors. LAMMPS can be run on multiple partitions via the "-partition" command-line switch as described in "this -section"_Section_start.html#2_4 of the manual. +section"_Section_start.html#2_6 of the manual. In the last 2 examples, if LAMMPS were run on 3 partitions, the same scripts could be used if the "index" and "loop" variables were @@ -283,7 +283,7 @@ simulation are run at different temperatures on different sets of processors, and Monte Carlo temperature swaps are performed between pairs of copies. -Use the -procs and -in "command-line switches"_Section_start.html#2_4 +Use the -procs and -in "command-line switches"_Section_start.html#2_6 to launch LAMMPS on multiple partitions. In your input script, define a set of temperatures, one for each @@ -405,10 +405,12 @@ This site M is located at a fixed distance away from the oxygen along the bisector of the HOH bond angle. A bond style of {harmonic} and an angle style of {harmonic} or {charmm} should also be used. -Two different four-point models (cutoff and long-range Coulombics) can -be implemented using LAMMPS pair styles with {tip4p} in their style -name. For both models, the bond lengths and bond angles should be -held fixed using the "fix shake"_fix_shake.html command. +Currently, only a four-point model for long-range Coulombics is +implemented via the LAMMPS "pair style +lj/cut/coul/long/tip4p"_pair_lj.html. We plan to add a cutoff +version in the future. For both models, the bond lengths and bond +angles should be held fixed using the "fix shake"_fix_shake.html +command. These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP4P model with a cutoff @@ -506,16 +508,16 @@ a new fix to LAMMPS. (2) Define a new LAMMPS command that calls the other code. This is conceptually similar to method (1), but in this case LAMMPS and the -other code are on a more equal footing. Note that now the other -code is not called during the timesteps of a LAMMPS run, but between +other code are on a more equal footing. Note that now the other code +is not called during the timestepping of a LAMMPS run, but between runs. The LAMMPS input script can be used to alternate LAMMPS runs with calls to the other code, invoked via the new command. The "run"_run.html command facilitates this with its {every} option, which makes it easy to run a few steps, invoke the command, run a few steps, invoke the command, etc. -In this scenario, the other code can be a library, called by the -command, or it could be a stand-alone code, invoked by a system() call +In this scenario, the other code can be called as a library, as in +(1), or it could be a stand-alone code, invoked by a system() call made by the command (assuming your parallel machine allows one or more processors to start up another program). In the latter case the stand-alone code could communicate with LAMMPS thru files that the @@ -531,49 +533,55 @@ Again, the "run"_run.html command has options that allow it to be invoked with minimal overhead (no setup or clean-up) if you wish to do multiple short runs, driven by another program. -"This section"_Section_start.html#2_2 of the documentation describes -how to build LAMMPS as a library. Once this is done, you can interface -with LAMMPS either via C++, C, or Fortran (or any other language that -supports a vanilla C-like interface, e.g. a scripting language). For -example, from C++ you could create an "instance" of LAMMPS, and -initialize it, pass it an input script to process, or execute +"This section"_Section_start.html#2_4 of the documentation describes +how to build LAMMPS as a library. Once this is done, you can +interface with LAMMPS either via C++, C, or Fortran (or any other +language that supports a vanilla C-like interface, e.g. a scripting +language). For example, from C++ you could create one (or more) +"instances" of LAMMPS, pass it an input script to process, or execute individual commands, all by invoking the correct class methods in -LAMMPS. From C or Fortran you would make function calls to do the -same things. Library.cpp and library.h contain such a C interface -that illustrates this with the functions: +LAMMPS. From C or Fortran you can make function calls to do the same +things. Library.cpp and library.h contain such a C interface with the +functions: -void lammps_open(int, char **, MPI_Comm); -void lammps_close(); -void lammps_file(char *); -char *lammps_command(char *); :pre +void lammps_open(int, char **, MPI_Comm, void **); +void lammps_close(void *); +void lammps_file(void *, char *); +char *lammps_command(doivd *, char *); :pre -The functions contain the C++ code you would need to put in a C++ -application that was invoking LAMMPS directly. +The functions contain C++ code you could write in a C++ application +that was invoking LAMMPS directly. Note that LAMMPS classes are +defined wihin a LAMMPS namespace (LAMMPS_NS) if you use them +from another C++ application. Two of the routines in library.cpp are of particular note. The lammps_open() function initiates LAMMPS and takes an MPI communicator -as an argument. LAMMPS will run on the set of processors in the -communicator. This means the calling code can run LAMMPS on all or a -subset of processors. For example, a wrapper script might decide to -alternate between LAMMPS and another code, allowing them both to run -on all the processors. Or it might allocate half the processors to -LAMMPS and half to the other code and run both codes simultaneously -before syncing them up periodically. +as an argument. It returns a pointer to a LAMMPS "object". As with +C++, the lammps_open() function can be called mutliple times, to +create multiple instances of LAMMPS. -Library.cpp also contains a lammps_command() function to which the -caller passes a single LAMMPS command (a string). Thus the calling -code can read or generate a series of LAMMPS commands (e.g. an input -script) one line at a time and pass it thru the library interface to -setup a problem and then run it. +LAMMPS will run on the set of processors in the communicator. This +means the calling code can run LAMMPS on all or a subset of +processors. For example, a wrapper script might decide to alternate +between LAMMPS and another code, allowing them both to run on all the +processors. Or it might allocate half the processors to LAMMPS and +half to the other code and run both codes simultaneously before +syncing them up periodically. -A few other sample routines are included in library.cpp, but the key -idea is that you can write any routines you wish to define an +Library.cpp contains a lammps_command() function to which the caller +passes a single LAMMPS command (a string). Thus the calling code can +read or generate a series of LAMMPS commands (e.g. an input script) +one line at a time and pass it thru the library interface to setup a +problem and then run it. + +A few other sample functions are included in library.cpp, but the key +idea is that you can write any functions you wish to define an interface for how your code talks to LAMMPS and add them to library.cpp and library.h. The routines you add can access any LAMMPS -data. The umbrella.cpp code in examples/couple is a simple example of -how a stand-alone code can link LAMMPS as a library, run LAMMPS on a -subset of processors, grab data from LAMMPS, change it, and put it -back into LAMMPS. +data. The examples/couple directory has example C++ and C codes which +show how a stand-alone code can link LAMMPS as a library, run LAMMPS +on a subset of processors, grab data from LAMMPS, change it, and put +it back into LAMMPS. :line diff --git a/doc/Section_modify.html b/doc/Section_modify.html index 887b903188..7ea5846db9 100644 --- a/doc/Section_modify.html +++ b/doc/Section_modify.html @@ -14,29 +14,34 @@ Section

    8. Modifying & extending LAMMPS

    LAMMPS is designed in a modular fashion so as to be easy to modify and -extend with new functionality. In this section, changes and additions -users can make are listed along with some minimal instructions. -Realistically, the best way to add a new feature is to find a similar -feature in LAMMPS and look at the corresponding source and header -files to figure out what it does. You will need some knowledge of C++ -to be able to understand the hi-level structure of LAMMPS and its -class organization, but functions (class methods) that do actual -computations are written in vanilla C-style code and operate on simple -C-style data structures (vectors and arrays). +extend with new functionality. In fact, about 75% if its source code +is files added in this fashion. +

    +

    In this section, changes and additions users can make are listed along +with minimal instructions. The best way to add a new feature is to +find a similar feature in LAMMPS and look at the corresponding source +and header files to figure out what it does. You will need some +knowledge of C++ to be able to understand the hi-level structure of +LAMMPS and its class organization, but functions (class methods) that +do actual computations are written in vanilla C-style code and operate +on simple C-style data structures (vectors and arrays).

    Most of the new features described in this section require you to -write a new C++ class (except for dump, thermo, and variable options, -described below, where you can make small edits to existing files). -Creating a new class requires 2 files, a source code file (*.cpp) and -a header file (*.h). Their contents are briefly discussed below. -Enabling LAMMPS to invoke the new class is as simple as adding two -definition lines to the style_user.h file, in the same syntax as the -existing LAMMPS classes are defined in the style.h file. +write a new C++ derived class (except for exceptions described below, +where you can make small edits to existing files). Creating a new +class requires 2 files, a source code file (*.cpp) and a header file +(*.h). The derived class must provide certain methods to work as a +new option. Depending on how different your new feature is compared +to existing features, you can either derive from the base class +itself, or from a derived class that already exists. Enabling LAMMPS +to invoke the new class is as simple as adding two lines to the +style_user.h file, in the same syntax as other LAMMPS classes are +specified in the style.h file.

    -

    The power of C++ and its object-orientation is that usually, all the -code and variables needed to define the new feature are contained in -the 2 files you write, and thus shouldn't make the rest of the code -more complex or cause side-effect bugs. +

    The advantage of C++ and its object-orientation is that all the code +and variables needed to define the new feature are in the 2 files you +write, and thus shouldn't make the rest of LAMMPS more complex or +cause side-effect bugs.

    Here is a concrete example. Suppose you write 2 files pair_foo.cpp and pair_foo.h that define a new class PairFoo that computes pairwise @@ -46,8 +51,8 @@ command like

    pair_style foo 0.1 3.5 
     
    -

    you simply need to put your 2 files in the LAMMPS src directory, add 2 -lines to the style_user.h file, and re-make the code. +

    you put your 2 files in the LAMMPS src directory, add 2 lines to the +style_user.h file, and re-make the code.

    The first line added to style_user.h would be

    @@ -69,108 +74,121 @@ the executable and can be invoked with a pair_style command like the example above. Arguments like 0.1 and 3.5 can be defined and processed by your new class.

    -

    Note that if you are using Makefile.list instead of Makefile to build -LAMMPS, you will need to explicitly add the names of your new .cpp and -.h file to Makefile.list. +

    Here is a list of the new features that can be added in this way:

    -

    Here is a list of the kinds of new features that can be added in this -way. The dump and thermo options do not typically require new styles; -LAMMPS can simply be recompiled after new code is added to -dump_custom.cpp or thermo_custom.cpp. -

    -
    • Pairwise potentials + -

      As illustrated by the pairwise example, these options are -referred to in the LAMMPS documentation as the "style" of a particular -command. +

      As illustrated by the pairwise example, these options are referred to +in the LAMMPS documentation as the "style" of a particular command.

      -

      The instructions below for each category will list the header file for -the parent class that these styles are sub-classes of. Public -variables in that file are ones used and set by the sub-classes which -are also used by the parent class. Sometimes they are also used by -the rest of LAMMPS. Virtual functions in the header file which are -set = 0 are ones you must define in your new class to give it the -functionality LAMMPS expects. Virtual functions that are not set to 0 -are functions you can optionally define. +

      The instructions below give the header file for the base class that +these styles are derived from. Public variables in that file are ones +used and set by the derived classes which are also used by the base +class. Sometimes they are also used by the rest of LAMMPS. Virtual +functions in the base class header file which are set = 0 are ones you +must define in your new derived class to give it the functionality +LAMMPS expects. Virtual functions that are not set to 0 are functions +you can optionally define.

      -

      Here are some additional guidelines for modifying LAMMPS and adding -new functionality: -

      -

      Think about whether what you want to do would be better as a pre- or -post-processing step. Many computations are more easily and more -quickly done that way. -

      -

      Don't do anything within the timestepping of a run that isn't -parallel. E.g. don't accumulate a bunch of data on a single processor -and analyze it. You run the risk of seriously degrading the parallel -efficiency. -

      -

      If your new feature reads arguments or writes output, make sure you -follow the unit conventions discussed by the units -command. -

      -

      If you add something you think is truly useful and doesn't impact -LAMMPS performance when it isn't used, send an email to the -developers. We might be -interested in adding it to the LAMMPS distribution. +

      Additionally, new output options can be added directly to the +thermo.cpp, dump_custom.cpp, and variable.cpp files as explained in +these sections:

      +
      -

      Pairwise potentials +

      Here are additional guidelines for modifying LAMMPS and adding new +functionality: +

      +
      • Think about whether what you want to do would be better as a pre- or +post-processing step. Many computations are more easily and more +quickly done that way. + +
      • Don't do anything within the timestepping of a run that isn't +parallel. E.g. don't accumulate a bunch of data on a single processor +and analyze it. You run the risk of seriously degrading the parallel +efficiency. + +
      • If your new feature reads arguments or writes output, make sure you +follow the unit conventions discussed by the units +command. + +
      • If you add something you think is truly useful and doesn't impact +LAMMPS performance when it isn't used, send an email to the +developers. We might be +interested in adding it to the LAMMPS distribution. +
      +
      + +
      + +

      Atom styles

      -

      All classes that compute pairwise interactions are sub-classes of the -Pair class. See the pair.h file for a list of methods this class -defines. +

      Classes that define an atom style are derived from the Atom class. +The atom style determines what quantities are associated with an atom. +A new atom style can be created if one of the existing atom styles +does not define all the arrays you need to store and communicate with +atoms.

      -

      Pair_lj_cut.cpp and pair_lj_cut.h are the simplest example of a Pair -class. They implement the lj/cut style of the -pair_style command. +

      Atom_vec_atomic.cpp is a simple example of an atom style.

      -

      Here is a brief description of the class methods in pair.h: +

      Here is a brief description of methods you define in your new derived +class. See atom.h for details.

      - - - - - - - - + + + + + + + + + + + + + + +
      compute the workhorse routine that computes the pairwise interactions
      settings reads the input script line with any arguments you define
      coeff set coefficients for one i,j type pair
      init_one perform initialization for one i,j type pair
      write & read_restart write/read i,j pair coeffs to restart files
      write & read_restart_settings write/read global settings to restart files
      single force and energy of a single pairwise interaction between 2 atoms
      compute_inner/middle/outer versions of compute used by rRESPA +
      grow re-allocate atom arrays to longer lengths
      copy copy info for one atom to another atom's array locations
      pack_comm store an atom's info in a buffer communicated every timestep
      unpack_comm retrieve an atom's info from the buffer
      pack_reverse store an atom's info in a buffer communicating partial forces
      unpack_reverse retrieve an atom's info from the buffer
      pack_border store an atom's info in a buffer communicated on neighbor re-builds
      unpack_border retrieve an atom's info from the buffer
      pack_exchange store all an atom's info to migrate to another processor
      unpack_exchange retrieve an atom's info from the buffer
      size_restart number of restart quantities associated with proc's atoms
      pack_restart pack atom quantities into a buffer
      unpack_restart unpack atom quantities from a buffer
      create_atom create an individual atom of this style
      data_atom parse an atom line from the data file
      memory_usage tally memory allocated by atom arrays
      -

      The inner/middle/outer routines are optional. Only a few of the -pairwise potentials use these in conjunction with rRESPA as set by the -run_style command. +

      The constructor of the derived class sets values for several variables +that you must set when defining a new atom style. The atom arrays +themselves are defined in atom.cpp. Search for the word "customize" +and you will find locations you will need to modify.


      Bond, angle, dihedral, improper potentials

      -

      All classes that compute molecular interactions are sub-classes of the -Bond, Angle, Dihedral, and Improper classes. See the bond.h, angle.h, -dihedral.h, and improper.h file for a list of methods these classes -defines. +

      Classes that compute molecular interactions are derived from the Bond, +Angle, Dihedral, and Improper classes. New styles can be created to +add new potentials to LAMMPS.

      -

      Bond_harmonic.cpp and bond_harmonic.h are the simplest example of a -Bond class. Ditto for the harmonic forms of the angle, dihedral, and -improper style commands. The bond_harmonic files implement the -harmonic style of the bond_style command. +

      Bond_harmonic.cpp is the simplest example of a bond style. Ditto for +the harmonic forms of the angle, dihedral, and improper style +commands.

      -

      Here is a brief description of the class methods in bond.h, angle.h, -etc: +

      Here is a brief description of methods you define in your new derived +bond class. See bond.h, angle.h, dihedral.h, and improper.h for +details.

      - + @@ -179,145 +197,85 @@ etc:
      -

      Dump options +

      Compute styles

      -

      There are several classes that print dump files (snapshots of atoms) -that are sub-classes of the Dump class. These include the -dump_atom.cpp, dump_bond.cpp, and dump_custom.cpp files. +

      Classes that compute scalar and vector quantities like temperature +and the pressure tensor, as well as classes that compute per-atom +quantities like kinetic energy and the centro-symmetry parameter +are derived from the Compute class. New styles can be created +to add new calculations to LAMMPS.

      -

      New dump classes can be added, but it is typically simpler to modify -the DumpCustom class contained in the dump_custom.cpp file. See the -dump command and its custom style for a list of what -atom information can already be dumped by DumpCustom. If the -attribute you want to dump is not in the list, or if you define a new -atom style with new attributes (e.g. atoms that store their own -magnetic moment), here is how to dump it out in a snapshot file: +

      Compute_temp.cpp is a simple example of computing a scalar +temperature. Compute_ke_atom.cpp is a simple example of computing +per-atom kinetic energy.

      -

      Search the dump_custom.cpp and dump_custom.h files for the word -"customize". It appears in roughly half a dozen locations. In each -of the locations you can add a bit of code that will extend the -DumpCustom class to enable it to dump a new quantity. E.g. you will -add a keyword, add an if test, add a new small method that packs the -requested data into a buffer, etc. For the latter, you can perform a -modest amount of computation in this method; see the pack_xs() -function for an example. -

      -

      If desired, a dump custom option can also compute more complicated -quantities by invoking a fix that computed quantities at the end of a -timestep (should be the same timestep the dump is invoked on). See -the ENERGY, CENTRO, and stress options (SXX, SYY, etc) in -dump_custom.cpp for examples. -

      -

      When you re-make LAMMPS, your new option should now be useable via the -dump custom command. -

      -
      - -

      Thermodynamic output options -

      -

      There is only one class that computes and prints thermodynamic -information to the screen and log file, although the -thermo_style command treats its options as styles. -

      -

      There are several styles defined in thermo.cpp: "one", "multi", and -"granular". There is also a flexible "custom" style which allows you -to specify what quantities will be printed each timestep where -thermodynamics is computed. See the thermo_style -command for a list of pre-defined quantities. -

      -

      Here is how you can extend the thermo output capabilities. Search the -thermo.cpp and thermo.h files for the word "customize" which will tell -you where to make these additions. Note that fixes can also print-out -thermodynamic quantities via the fix_modify command, -so you do not need to modify thermo.cpp to print fix information. -

      -

      If you want to create a new style (like "one" or "granular") that -prints a collection of pre-defined quantities, you add a few lines -that define the new style to thermo.cpp. First, add a #DEFINE line at -the top of the file which lists the quantities to print. Then add the -style name you have chosen to the if test in the constructor to copy -the defined string to the line variable. -

      -

      You can also add new quantities to the custom list. Add your new -keyword to the if test in the parse_fields() function where the call -to addfield() specifies the text string (8 character max) that will be -printed with the quantity, the function that will compute it, and the -data type (INT,FLOAT) of the quantity. Then at the bottom of the -file, add a function compute_*() which computes the quantity you wish -to print. The function assigns the quantity to the variable "dvalue" -if it is a floating-point quantity, or to "ivalue" if it is an -integer. See the other compute_*() functions for examples of how -various quantities can be accessed, computed, summed across -processors, normalized as per-atom values, etc. Also, if it makes -sense to allow the quantity to be stored in a variable in the input -script, add a couple of lines to the compute_value() function that is -called when a variable is evaluated. Finally, add a prototype for -your new compute method to thermo.h. -

      -
      - -

      Temperature computation options -

      -

      All classes that compute the temperature of the system are sub-classes -of the Temperature class. See the temperature.h file for a list of -methods these classes defines. Temperatures are computed by LAMMPS -when velocities are set, when thermodynamics are computed, and when -temperature is controlled by various thermostats like the fix -nvt of fix langevin commands. -

      -

      Temp_full.cpp and temp_full.h are the simplest example of a -Temperature class. They implement the full style of the -temperature command. -

      -

      Here is a brief description of the class methods in temperature.h: +

      Here is a brief description of methods you define in your new derived +class. See compute.h for details.

      compute the workhorse routine that computes the molecular interactions
      compute compute the molecular interactions
      coeff set coefficients for one bond type
      equilibrium_distance length of bond, used by SHAKE
      write & read_restart writes/reads coeffs to restart files
      - - + + + + + + +
      init setup the temperature computation
      compute compute and return temperature +
      compute_scalar compute a scalar quantity
      compute_vector compute a vector of quantities
      compute_peratom compute one or more quantities per atom
      pack_comm pack a buffer with items to communicate
      unpack_comm unpack the buffer
      pack_reverse pack a buffer with items to reverse communicate
      unpack_reverse unpack the buffer
      memory_usage tally memory usage

      -

      Region geometry options +

      Dump styles

      -

      All classes that define geometric regions are sub-classes of the -Region class. See the region.h file for a list of methods these -classes defines. Regions are used elsewhere in LAMMPS to group atoms, -delete atoms to create a void, insert atoms in a specified region, -etc. +

      Dump custom output options +

      +

      Classes that dump per-atom info to files are derived from the Dump +class. To dump new quantities or in a new format, a new derived dump +class can be added, but it is typically simpler to modify the +DumpCustom class contained in the dump_custom.cpp file.

      -

      Region_sphere.cpp and region_sphere.h are the simplest example of a -Region class. They implement the sphere style of the -region command. +

      Dump_atom.cpp is a simple example of a derived dump class.

      -

      Here is a brief description of the single class method required: +

      Here is a brief description of methods you define in your new derived +class. See dump.h for details.

      - + + +
      match determine whether a point is in the region +
      write_header write the header section of a snapshot of atoms
      count count the number of lines a processor will output
      pack pack a proc's output data into a buffer
      write_data write a proc's data to a file
      +

      See the dump command and its custom style for a list of +keywords for atom information that can already be dumped by +DumpCustom. It includes options to dump per-atom info from Compute +classes, so adding a new derived Compute class is one way to calculate +new quantities to dump. +

      +

      Alternatively, you can add new keywords to the dump custom command. +Search for the word "customize" in dump_custom.cpp to see the +half-dozen or so locations where code will need to be added. +


      -

      Fix options +

      Fix styles

      In LAMMPS, a "fix" is any operation that is computed during timestepping that alters some property of the system. Essentially everything that happens during a simulation besides force computation, -neighbor list manipulation, and output, is a "fix". This includes -time integration (update of velocity and coordinates), force -constraints (SHAKE or walls), and diagnostics (compute a diffusion -coefficient). See the fix.h file for a list of methods these classes -defines. +neighbor list construction, and output, is a "fix". This includes +time integration (update of coordinates and velocities), force +constraints or boundary conditions (SHAKE or walls), and diagnostics +(compute a diffusion coefficient). New styles can be created to add +new options to LAMMPS.

      -

      There are dozens of fix options in LAMMPS; choose one as a template -that is similar to what you want to implement. They can be as simple -as zeroing out forces (see fix enforce2d which -corresponds to the enforce2d style) or as complicated as applying -SHAKE constraints on bonds and angles (see fix shake -which corresponds to the shake style) which involves many extra -computations. +

      Fix_setforce.cpp is a simple example of setting forces on atoms to +prescribed values. There are dozens of fix options already in LAMMPS; +choose one as a template that is similar to what you want to +implement.

      -

      Here is a brief description of the class methods in fix.h: +

      Here is a brief description of methods you can define in your new +derived class. See fix.h for details.

      @@ -347,8 +305,7 @@ computations. - -
      setmask determines when the fix is called during the timestep
      unpack_comm unpack a buffer to communicate a per-atom quantity
      pack_reverse_comm pack a buffer to reverse communicate a per-atom quantity
      unpack_reverse_comm unpack a buffer to reverse communicate a per-atom quantity
      thermo_fields define quantities for thermodynamic output
      thermo_compute compute thermodynamic quantities +
      thermo compute quantities for thermodynamic output

      Typically, only a small fraction of these methods are defined for a @@ -363,130 +320,201 @@ when to call the fix. By convention, this is the first argument the fix defines (after the ID, group-ID, style).

      If the fix needs to store information for each atom that persists from -timestep to timestep, it can manage that memory and migrate it with -the atoms as they move from processors to processor by implementing -the grow_arrays, copy_arrays, pack_exchange, and unpack_exchange -methods. Similarly, the pack_restart and unpack_restart methods can be -implemented to store information about the fix in restart files. If -you wish an integrator or force constraint fix to work with rRESPA (see -the run_style command), the initial_integrate, -post_force_integrate, and final_integrate_respa methods can be -implemented. The thermo_fields and thermo_compute methods enable a -fix to contribute values to thermodynamic output, as printed +timestep to timestep, it can manage that memory and migrate the info +with the atoms as they move from processors to processor by +implementing the grow_arrays, copy_arrays, pack_exchange, and +unpack_exchange methods. Similarly, the pack_restart and +unpack_restart methods can be implemented to store information about +the fix in restart files. If you wish an integrator or force +constraint fix to work with rRESPA (see the run_style +command), the initial_integrate, post_force_integrate, and +final_integrate_respa methods can be implemented. The thermo method +enables a fix to contribute values to thermodynamic output, as printed quantities and/or to be summed to the potential energy of the system.


      -

      Atom options +

      Input script commands

      -

      All classes that define an atom style are sub-classes of the Atom -class. See the atom.h file for a list of methods these classes -defines. The atom style determines what quantities are associated -with an atom in a LAMMPS simulation. If one of the existing atom -styles does not define all the arrays you need to store with an atom, -then a new atom class can be created. -

      -

      Atom_atomic.cpp and atom_atomic.h are the simplest example of an Atom -class. They implement the atomic style of the -atom_style command. -

      -

      Here is a brief description of the class methods in atom.h: -

      -
      - - - - - - - - - -
      copy copy info for one atom to another atom's array location
      pack_comm store an atom's info in a buffer communicated every timestep
      unpack_comm retrieve an atom's info from the buffer
      pack_reverse store an atom's info in a buffer communicating partial forces
      unpack_reverse retrieve an atom's info from the buffer
      pack_border store an atom's info in a buffer communicated on neighbor re-builds
      unpack_border retrieve an atom's info from the buffer
      pack_exchange store all an atom's info to migrate to another processor
      unpack_exchange retrieve an atom's info from the buffer
      -
      - -

      There are also several methods in atom.cpp you will need to augment -with information about your new atom class, following the patterns of -the other atom styles. These routines are so similar for all classes, -that it was simpler to just have one master routine for all classes. -

      -
      - - - - - - - - - - - - -
      constructor create style variable and atom array ptrs to NULL
      destructor free memory for atom arrays
      set_style set style variable
      check_style check for pure style vs hybrid style
      style2arg convert style variables to keywords
      grow re-allocate atom arrays to longer lengths
      unpack_data parse atom lines from data file
      create_one create an individual atom of this style
      size_restart number of restart quantities associated with proc's atoms
      pack_restart pack atom quantities into a buffer
      unpack_restart unpack atom quantities from a buffer
      memory_usage memory allocated by atom arrays
      -
      - -
      - -

      Variable options -

      -

      The variable class stores and evaluates input script variables $a, $b, -... $z, as described in this section. -Equal-style variables are defined by an equation that is evaluated -each time the variable is used. The equation can include functions, -vectors, keywords, and numbers as described in the -variable command. The list of valid functions, -vectors, and keywords, can be extended by adding a few lines of code -to the evaluate() method at the end of the variable.cpp file. Search -for the word "customize" to find the correct locations for adding -code. -

      -

      A new function (e.g. foo(arg1,arg2,...)) can be added in the section -that starts with the comment -

      -
      // customize by adding function to this list and to if statement 
      -
      -

      A new vector (e.g. q) can be added in the section that starts with -the comment -

      -
      // customize by adding vector to this list and to if statement 
      -
      -

      A new keyword (e.g. mysum) can be added in the section that starts with -the comment -

      -
      // customize by adding keyword to this list and to if statement 
      -
      -

      Note that keywords supported by the thermo_style -custom command are evaluated by the thermo routines, -so do not need to be added to variable.cpp. -

      -
      - -

      New top-level commands -

      -

      It is possible to add a new command to a LAMMPS input script as -opposed to adding a new style to an existing command (atom_style, -pair_style, fix, etc). For example the create_atoms, read_data, -velocity, and run commands are all top-level LAMMPS commands that are -listed in the Command section of style.h. When such a command is -encountered in the LAMMPS input script, the topmost level of LAMMPS -(lammps.cpp) simply creates a class with the corresponding name, +

      New commands can be added to LAMMPS input scripts by adding new +classes that have a "command" method and are listed in the Command +sections of style.h (or style_user.h). For example, the create_atoms, +read_data, velocity, and run commands are all implemented in this +fashion. When such a command is encountered in the LAMMPS input +script, LAMMPS simply creates a class with the corresponding name, invokes the "command" method of the class, and passes it the arguments from the input script. The command method can perform whatever -operations it wishes on the LAMMPS data structures. +operations it wishes on LAMMPS data structures.

      -

      Thus to add a new command, you simply need to add a *.cpp and *.h file -containing a single class: +

      The single method your new class must define is as follows:

      command operations performed by the new command
      -

      Of course, the new class can define other methods and variables that -it uses internally. +

      Of course, the new class can define other methods and variables as +needed.


      +

      Kspace computations +

      +

      Classes that compute long-range Coulombic interactions via K-space +represenations (Ewald, PPPM) are derived from the KSpace class. New +styles can be created to add new K-space options to LAMMPS. +

      +

      Ewald.cpp is an example of computing K-space interactions. +

      +

      Here is a brief description of methods you define in your new derived +class. See kspace.h for details. +

      +
      + + + +
      init initialize the calculation before a run
      setup computation before the 1st timestep of a run
      compute every-timestep computation
      memory_usage tally of memory usage +
      + +
      + +

      Minimization solvers +

      +

      Classes that perform energy minimization derived from the Min class. +New styles can be created to add new minimization algorithms to +LAMMPS. +

      +

      Min_cg.cpp is an example of conjugate gradient minimization. +

      +

      Here is a brief description of methods you define in your new derived +class. See min.h for details. +

      +
      + + +
      init initialize the minimization before a run
      run perform the minimization
      memory_usage tally of memory usage +
      + +
      + +

      Pairwise potentials +

      +

      Classes that compute pairwise interactions are derived from the Pair +class. In LAMMPS, pairwise calculation include manybody potentials +such as EAM or Tersoff where particles interact without a static bond +topology. New styles can be created to add new pair potentials to +LAMMPS. +

      +

      Pair_lj_cut.cpp is a simple example of a Pair class, though it +includes some optional methods to enable its use with rRESPA. +

      +

      Here is a brief description of the class methods in pair.h: +

      +
      + + + + + + + + +
      compute workhorse routine that computes pairwise interactions
      settings reads the input script line with arguments you define
      coeff set coefficients for one i,j type pair
      init_one perform initialization for one i,j type pair
      init_style initialization specific to this pair style
      write & read_restart write/read i,j pair coeffs to restart files
      write & read_restart_settings write/read global settings to restart files
      single force and energy of a single pairwise interaction between 2 atoms
      compute_inner/middle/outer versions of compute used by rRESPA +
      + +

      The inner/middle/outer routines are optional. +

      +
      + +

      Region styles +

      +

      Classes that define geometric regions are derived from the Region +class. Regions are used elsewhere in LAMMPS to group atoms, delete +atoms to create a void, insert atoms in a specified region, etc. New +styles can be created to add new region shapes to LAMMPS. +

      +

      Region_sphere.cpp is an example of a spherical region. +

      +

      Here is a brief description of methods you define in your new derived +class. See region.h for details. +

      +
      +
      match determine whether a point is in the region +
      + +
      + +

      Thermodynamic output options +

      +

      There is one class that computes and prints thermodynamic information +to the screen and log file; see the file thermo.cpp. +

      +

      There are several styles defined in thermo.cpp: "one", "multi", +"granular", etc. There is also a flexible "custom" style which allows +the user to explicitly list keywords for quantities to print when +thermodynamic info is output. See the +thermo_style command for a list of defined +quantities. +

      +

      The thermo styles (one, multi, etc) are simply lists of keywords. +Adding a new style thus only requies defining a new list of keywords. +Search for the word "customize" with references to "thermo style" in +thermo.cpp to see the two locations where code will need to be added. +

      +

      New keywords can also be added to thermo.cpp to compute new quantities +for output. Search for the word "customize" with references to +"keyword" in thermo.cpp to see the several locations where code will +need to be added. +

      +

      Note that the thermo_style custom command already allows +for thermo output of quantities calculated by fixes, +computes, and variables. Thus, it may +be simpler to compute what you wish via one of those constructs, than +by adding a new keyword to the thermo command. +

      +
      + +

      Variable options +

      +

      There is one class that computes and stores variable +information in LAMMPS; see the file variable.cpp. The value +associated with a variable can be periodically printed to the screen +via the print, fix print, or +thermo_style custom commands. Variables of style +"equal" can compute complex equations that involve the following types +of arguments: +

      +

      thermo keywords = ke, vol, atoms, ... +other variables = v_a, v_myvar, ... +math functions = div(x,y), mult(x,y), add(x,y), ... +group functions = mass(group), xcm(group,x), ... +atom values = x123, y3, vx34, ... +compute values = c_mytemp0, c_thermo_press3, ... +

      +

      Adding keywords for the thermo_style custom command +(which can then be accessed by variables) was discussed +here on this page. +

      +

      Adding a new math function of one or two arguments can be done by +editing one section of the Variable::evaulate() method. Search for +the word "customize" to find the appropriate location. +

      +

      Adding a new group function can be done by editing one section of the +Variable::evaulate() method. Search for the word "customize" to find +the appropriate location. You may need to add a new method to the +Group class as well (see the group.cpp file). +

      +

      Accessing a new atom-based vector can be done by editing one section +of the Variable::evaulate() method. Search for the word "customize" +to find the appropriate location. +

      +

      Adding new compute styles (whose calculated values can +then be accessed by variables) was discussed +here on this page. +

      +
      + +
      +

      (Foo) Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997). diff --git a/doc/Section_modify.txt b/doc/Section_modify.txt index be68a29efc..df8a158a9f 100644 --- a/doc/Section_modify.txt +++ b/doc/Section_modify.txt @@ -11,29 +11,34 @@ Section"_Section_errors.html :c 8. Modifying & extending LAMMPS :h3 LAMMPS is designed in a modular fashion so as to be easy to modify and -extend with new functionality. In this section, changes and additions -users can make are listed along with some minimal instructions. -Realistically, the best way to add a new feature is to find a similar -feature in LAMMPS and look at the corresponding source and header -files to figure out what it does. You will need some knowledge of C++ -to be able to understand the hi-level structure of LAMMPS and its -class organization, but functions (class methods) that do actual -computations are written in vanilla C-style code and operate on simple -C-style data structures (vectors and arrays). +extend with new functionality. In fact, about 75% if its source code +is files added in this fashion. + +In this section, changes and additions users can make are listed along +with minimal instructions. The best way to add a new feature is to +find a similar feature in LAMMPS and look at the corresponding source +and header files to figure out what it does. You will need some +knowledge of C++ to be able to understand the hi-level structure of +LAMMPS and its class organization, but functions (class methods) that +do actual computations are written in vanilla C-style code and operate +on simple C-style data structures (vectors and arrays). Most of the new features described in this section require you to -write a new C++ class (except for dump, thermo, and variable options, -described below, where you can make small edits to existing files). -Creating a new class requires 2 files, a source code file (*.cpp) and -a header file (*.h). Their contents are briefly discussed below. -Enabling LAMMPS to invoke the new class is as simple as adding two -definition lines to the style_user.h file, in the same syntax as the -existing LAMMPS classes are defined in the style.h file. +write a new C++ derived class (except for exceptions described below, +where you can make small edits to existing files). Creating a new +class requires 2 files, a source code file (*.cpp) and a header file +(*.h). The derived class must provide certain methods to work as a +new option. Depending on how different your new feature is compared +to existing features, you can either derive from the base class +itself, or from a derived class that already exists. Enabling LAMMPS +to invoke the new class is as simple as adding two lines to the +style_user.h file, in the same syntax as other LAMMPS classes are +specified in the style.h file. -The power of C++ and its object-orientation is that usually, all the -code and variables needed to define the new feature are contained in -the 2 files you write, and thus shouldn't make the rest of the code -more complex or cause side-effect bugs. +The advantage of C++ and its object-orientation is that all the code +and variables needed to define the new feature are in the 2 files you +write, and thus shouldn't make the rest of LAMMPS more complex or +cause side-effect bugs. Here is a concrete example. Suppose you write 2 files pair_foo.cpp and pair_foo.h that define a new class PairFoo that computes pairwise @@ -43,8 +48,8 @@ command like pair_style foo 0.1 3.5 :pre -you simply need to put your 2 files in the LAMMPS src directory, add 2 -lines to the style_user.h file, and re-make the code. +you put your 2 files in the LAMMPS src directory, add 2 lines to the +style_user.h file, and re-make the code. The first line added to style_user.h would be @@ -66,107 +71,119 @@ the executable and can be invoked with a pair_style command like the example above. Arguments like 0.1 and 3.5 can be defined and processed by your new class. -Note that if you are using Makefile.list instead of Makefile to build -LAMMPS, you will need to explicitly add the names of your new .cpp and -.h file to Makefile.list. +Here is a list of the new features that can be added in this way: -Here is a list of the kinds of new features that can be added in this -way. The dump and thermo options do not typically require new styles; -LAMMPS can simply be recompiled after new code is added to -dump_custom.cpp or thermo_custom.cpp. - -"Pairwise potentials"_#pair +"Atom styles"_#atom "Bond, angle, dihedral, improper potentials"_#bond -"Dump options"_#dump -"Thermodynamic output options"_#thermo -"Temperature computation options"_#temp -"Region geometry options"_#region -"Fix options"_#fix which include integrators, \ +"Compute styles"_#compute +"Dump styles"_#dump +"Fix styles"_#fix which include integrators, \ temperature and pressure control, force constraints, \ boundary conditions, diagnostic output, etc -"Atom options"_#atom -"Variable options"_#variable -"New top-level commands"_#command :ul +"Input script commands"_#command +"Kspace computations"_#kspace +"Minimization solvers"_#min +"Pairwise potentials"_#pair +"Region styles"_#region :ul -As illustrated by the pairwise example, these options are -referred to in the LAMMPS documentation as the "style" of a particular -command. +As illustrated by the pairwise example, these options are referred to +in the LAMMPS documentation as the "style" of a particular command. -The instructions below for each category will list the header file for -the parent class that these styles are sub-classes of. Public -variables in that file are ones used and set by the sub-classes which -are also used by the parent class. Sometimes they are also used by -the rest of LAMMPS. Virtual functions in the header file which are -set = 0 are ones you must define in your new class to give it the -functionality LAMMPS expects. Virtual functions that are not set to 0 -are functions you can optionally define. +The instructions below give the header file for the base class that +these styles are derived from. Public variables in that file are ones +used and set by the derived classes which are also used by the base +class. Sometimes they are also used by the rest of LAMMPS. Virtual +functions in the base class header file which are set = 0 are ones you +must define in your new derived class to give it the functionality +LAMMPS expects. Virtual functions that are not set to 0 are functions +you can optionally define. -Here are some additional guidelines for modifying LAMMPS and adding -new functionality: +Additionally, new output options can be added directly to the +thermo.cpp, dump_custom.cpp, and variable.cpp files as explained in +these sections: + +"Dump custom output options"_#dump_custom +"Thermodynamic output options"_#thermo +"Variable options"_#variable :ul + +:line + +Here are additional guidelines for modifying LAMMPS and adding new +functionality: Think about whether what you want to do would be better as a pre- or post-processing step. Many computations are more easily and more -quickly done that way. +quickly done that way. :ulb,l Don't do anything within the timestepping of a run that isn't parallel. E.g. don't accumulate a bunch of data on a single processor and analyze it. You run the risk of seriously degrading the parallel -efficiency. +efficiency. :l If your new feature reads arguments or writes output, make sure you follow the unit conventions discussed by the "units"_units.html -command. +command. :l If you add something you think is truly useful and doesn't impact LAMMPS performance when it isn't used, send an email to the "developers"_http://lammps.sandia.gov/authors.html. We might be -interested in adding it to the LAMMPS distribution. +interested in adding it to the LAMMPS distribution. :l,ule +:line :line -Pairwise potentials :link(pair),h4 +Atom styles :link(atom),h4 -All classes that compute pairwise interactions are sub-classes of the -Pair class. See the pair.h file for a list of methods this class -defines. +Classes that define an atom style are derived from the Atom class. +The atom style determines what quantities are associated with an atom. +A new atom style can be created if one of the existing atom styles +does not define all the arrays you need to store and communicate with +atoms. -Pair_lj_cut.cpp and pair_lj_cut.h are the simplest example of a Pair -class. They implement the {lj/cut} style of the -"pair_style"_pair_style.html command. +Atom_vec_atomic.cpp is a simple example of an atom style. -Here is a brief description of the class methods in pair.h: +Here is a brief description of methods you define in your new derived +class. See atom.h for details. -compute: the workhorse routine that computes the pairwise interactions -settings: reads the input script line with any arguments you define -coeff: set coefficients for one i,j type pair -init_one: perform initialization for one i,j type pair -write & read_restart: write/read i,j pair coeffs to restart files -write & read_restart_settings: write/read global settings to restart files -single: force and energy of a single pairwise interaction between 2 atoms -compute_inner/middle/outer: versions of compute used by rRESPA :tb(s=:) +grow: re-allocate atom arrays to longer lengths +copy: copy info for one atom to another atom's array locations +pack_comm: store an atom's info in a buffer communicated every timestep +unpack_comm: retrieve an atom's info from the buffer +pack_reverse: store an atom's info in a buffer communicating partial forces +unpack_reverse: retrieve an atom's info from the buffer +pack_border: store an atom's info in a buffer communicated on neighbor re-builds +unpack_border: retrieve an atom's info from the buffer +pack_exchange: store all an atom's info to migrate to another processor +unpack_exchange: retrieve an atom's info from the buffer +size_restart: number of restart quantities associated with proc's atoms +pack_restart: pack atom quantities into a buffer +unpack_restart: unpack atom quantities from a buffer +create_atom: create an individual atom of this style +data_atom: parse an atom line from the data file +memory_usage: tally memory allocated by atom arrays :tb(s=:) -The inner/middle/outer routines are optional. Only a few of the -pairwise potentials use these in conjunction with rRESPA as set by the -"run_style"_run_style.html command. +The constructor of the derived class sets values for several variables +that you must set when defining a new atom style. The atom arrays +themselves are defined in atom.cpp. Search for the word "customize" +and you will find locations you will need to modify. :line Bond, angle, dihedral, improper potentials :link(bond),h4 -All classes that compute molecular interactions are sub-classes of the -Bond, Angle, Dihedral, and Improper classes. See the bond.h, angle.h, -dihedral.h, and improper.h file for a list of methods these classes -defines. +Classes that compute molecular interactions are derived from the Bond, +Angle, Dihedral, and Improper classes. New styles can be created to +add new potentials to LAMMPS. -Bond_harmonic.cpp and bond_harmonic.h are the simplest example of a -Bond class. Ditto for the harmonic forms of the angle, dihedral, and -improper style commands. The bond_harmonic files implement the -{harmonic} style of the "bond_style"_bond_style.html command. +Bond_harmonic.cpp is the simplest example of a bond style. Ditto for +the harmonic forms of the angle, dihedral, and improper style +commands. -Here is a brief description of the class methods in bond.h, angle.h, -etc: +Here is a brief description of methods you define in your new derived +bond class. See bond.h, angle.h, dihedral.h, and improper.h for +details. -compute: the workhorse routine that computes the molecular interactions +compute: compute the molecular interactions coeff: set coefficients for one bond type equilibrium_distance: length of bond, used by SHAKE write & read_restart: writes/reads coeffs to restart files @@ -174,141 +191,80 @@ single: force and energy of a single bond :tb(s=:) :line -Dump options :link(dump),h4 +Compute styles :link(compute),h4 -There are several classes that print dump files (snapshots of atoms) -that are sub-classes of the Dump class. These include the -dump_atom.cpp, dump_bond.cpp, and dump_custom.cpp files. +Classes that compute scalar and vector quantities like temperature +and the pressure tensor, as well as classes that compute per-atom +quantities like kinetic energy and the centro-symmetry parameter +are derived from the Compute class. New styles can be created +to add new calculations to LAMMPS. -New dump classes can be added, but it is typically simpler to modify -the DumpCustom class contained in the dump_custom.cpp file. See the -"dump"_dump.html command and its {custom} style for a list of what -atom information can already be dumped by DumpCustom. If the -attribute you want to dump is not in the list, or if you define a "new -atom style"_#atom with new attributes (e.g. atoms that store their own -magnetic moment), here is how to dump it out in a snapshot file: +Compute_temp.cpp is a simple example of computing a scalar +temperature. Compute_ke_atom.cpp is a simple example of computing +per-atom kinetic energy. -Search the dump_custom.cpp and dump_custom.h files for the word -"customize". It appears in roughly half a dozen locations. In each -of the locations you can add a bit of code that will extend the -DumpCustom class to enable it to dump a new quantity. E.g. you will -add a keyword, add an if test, add a new small method that packs the -requested data into a buffer, etc. For the latter, you can perform a -modest amount of computation in this method; see the pack_xs() -function for an example. +Here is a brief description of methods you define in your new derived +class. See compute.h for details. -If desired, a dump custom option can also compute more complicated -quantities by invoking a fix that computed quantities at the end of a -timestep (should be the same timestep the dump is invoked on). See -the ENERGY, CENTRO, and stress options (SXX, SYY, etc) in -dump_custom.cpp for examples. - -When you re-make LAMMPS, your new option should now be useable via the -dump custom command. +compute_scalar: compute a scalar quantity +compute_vector: compute a vector of quantities +compute_peratom: compute one or more quantities per atom +pack_comm: pack a buffer with items to communicate +unpack_comm: unpack the buffer +pack_reverse: pack a buffer with items to reverse communicate +unpack_reverse: unpack the buffer +memory_usage: tally memory usage :tb(s=:) :line -Thermodynamic output options :link(thermo),h4 +Dump styles :link(dump),h4 +Dump custom output options :link(dump_custom),h4 -There is only one class that computes and prints thermodynamic -information to the screen and log file, although the -"thermo_style"_thermo_style.html command treats its options as styles. +Classes that dump per-atom info to files are derived from the Dump +class. To dump new quantities or in a new format, a new derived dump +class can be added, but it is typically simpler to modify the +DumpCustom class contained in the dump_custom.cpp file. -There are several styles defined in thermo.cpp: "one", "multi", and -"granular". There is also a flexible "custom" style which allows you -to specify what quantities will be printed each timestep where -thermodynamics is computed. See the "thermo_style"_thermo_style.html -command for a list of pre-defined quantities. +Dump_atom.cpp is a simple example of a derived dump class. -Here is how you can extend the thermo output capabilities. Search the -thermo.cpp and thermo.h files for the word "customize" which will tell -you where to make these additions. Note that fixes can also print-out -thermodynamic quantities via the "fix_modify"_fix_modify.html command, -so you do not need to modify thermo.cpp to print fix information. +Here is a brief description of methods you define in your new derived +class. See dump.h for details. -If you want to create a new style (like "one" or "granular") that -prints a collection of pre-defined quantities, you add a few lines -that define the new style to thermo.cpp. First, add a #DEFINE line at -the top of the file which lists the quantities to print. Then add the -style name you have chosen to the if test in the constructor to copy -the defined string to the line[] variable. +write_header: write the header section of a snapshot of atoms +count: count the number of lines a processor will output +pack: pack a proc's output data into a buffer +write_data: write a proc's data to a file :tb(s=:) -You can also add new quantities to the custom list. Add your new -keyword to the if test in the parse_fields() function where the call -to addfield() specifies the text string (8 character max) that will be -printed with the quantity, the function that will compute it, and the -data type (INT,FLOAT) of the quantity. Then at the bottom of the -file, add a function compute_*() which computes the quantity you wish -to print. The function assigns the quantity to the variable "dvalue" -if it is a floating-point quantity, or to "ivalue" if it is an -integer. See the other compute_*() functions for examples of how -various quantities can be accessed, computed, summed across -processors, normalized as per-atom values, etc. Also, if it makes -sense to allow the quantity to be stored in a variable in the input -script, add a couple of lines to the compute_value() function that is -called when a variable is evaluated. Finally, add a prototype for -your new compute method to thermo.h. +See the "dump"_dump.html command and its {custom} style for a list of +keywords for atom information that can already be dumped by +DumpCustom. It includes options to dump per-atom info from Compute +classes, so adding a new derived Compute class is one way to calculate +new quantities to dump. + +Alternatively, you can add new keywords to the dump custom command. +Search for the word "customize" in dump_custom.cpp to see the +half-dozen or so locations where code will need to be added. :line -Temperature computation options :link(temp),h4 - -All classes that compute the temperature of the system are sub-classes -of the Temperature class. See the temperature.h file for a list of -methods these classes defines. Temperatures are computed by LAMMPS -when velocities are set, when thermodynamics are computed, and when -temperature is controlled by various thermostats like the "fix -nvt"_fix_nvt.html of "fix langevin"_fix_langevin.html commands. - -Temp_full.cpp and temp_full.h are the simplest example of a -Temperature class. They implement the {full} style of the -"temperature"_temperature.html command. - -Here is a brief description of the class methods in temperature.h: - -init: setup the temperature computation -compute: compute and return temperature :tb(s=:) - -:line - -Region geometry options :link(region),h4 - -All classes that define geometric regions are sub-classes of the -Region class. See the region.h file for a list of methods these -classes defines. Regions are used elsewhere in LAMMPS to group atoms, -delete atoms to create a void, insert atoms in a specified region, -etc. - -Region_sphere.cpp and region_sphere.h are the simplest example of a -Region class. They implement the {sphere} style of the -"region"_region.html command. - -Here is a brief description of the single class method required: - -match: determine whether a point is in the region :tb(s=:) - -:line - -Fix options :link(fix),h4 +Fix styles :link(fix),h4 In LAMMPS, a "fix" is any operation that is computed during timestepping that alters some property of the system. Essentially everything that happens during a simulation besides force computation, -neighbor list manipulation, and output, is a "fix". This includes -time integration (update of velocity and coordinates), force -constraints (SHAKE or walls), and diagnostics (compute a diffusion -coefficient). See the fix.h file for a list of methods these classes -defines. +neighbor list construction, and output, is a "fix". This includes +time integration (update of coordinates and velocities), force +constraints or boundary conditions (SHAKE or walls), and diagnostics +(compute a diffusion coefficient). New styles can be created to add +new options to LAMMPS. -There are dozens of fix options in LAMMPS; choose one as a template -that is similar to what you want to implement. They can be as simple -as zeroing out forces (see "fix enforce2d"_fix_enforce2d.html which -corresponds to the {enforce2d} style) or as complicated as applying -SHAKE constraints on bonds and angles (see "fix shake"_fix_shake.html -which corresponds to the {shake} style) which involves many extra -computations. +Fix_setforce.cpp is a simple example of setting forces on atoms to +prescribed values. There are dozens of fix options already in LAMMPS; +choose one as a template that is similar to what you want to +implement. -Here is a brief description of the class methods in fix.h: +Here is a brief description of methods you can define in your new +derived class. See fix.h for details. setmask: determines when the fix is called during the timestep init: initialization before a run @@ -337,8 +293,7 @@ pack_comm: pack a buffer to communicate a per-atom quantity unpack_comm: unpack a buffer to communicate a per-atom quantity pack_reverse_comm: pack a buffer to reverse communicate a per-atom quantity unpack_reverse_comm: unpack a buffer to reverse communicate a per-atom quantity -thermo_fields: define quantities for thermodynamic output -thermo_compute: compute thermodynamic quantities :tb(s=:) +thermo: compute quantities for thermodynamic output :tb(s=:) Typically, only a small fraction of these methods are defined for a particular fix. Setmask is mandatory, as it determines when the fix @@ -352,122 +307,188 @@ when to call the fix. By convention, this is the first argument the fix defines (after the ID, group-ID, style). If the fix needs to store information for each atom that persists from -timestep to timestep, it can manage that memory and migrate it with -the atoms as they move from processors to processor by implementing -the grow_arrays, copy_arrays, pack_exchange, and unpack_exchange -methods. Similarly, the pack_restart and unpack_restart methods can be -implemented to store information about the fix in restart files. If -you wish an integrator or force constraint fix to work with rRESPA (see -the "run_style"_run_style.html command), the initial_integrate, -post_force_integrate, and final_integrate_respa methods can be -implemented. The thermo_fields and thermo_compute methods enable a -fix to contribute values to thermodynamic output, as printed +timestep to timestep, it can manage that memory and migrate the info +with the atoms as they move from processors to processor by +implementing the grow_arrays, copy_arrays, pack_exchange, and +unpack_exchange methods. Similarly, the pack_restart and +unpack_restart methods can be implemented to store information about +the fix in restart files. If you wish an integrator or force +constraint fix to work with rRESPA (see the "run_style"_run_style.html +command), the initial_integrate, post_force_integrate, and +final_integrate_respa methods can be implemented. The thermo method +enables a fix to contribute values to thermodynamic output, as printed quantities and/or to be summed to the potential energy of the system. :line -Atom options :link(atom),h4 +Input script commands :link(command),h4 -All classes that define an atom style are sub-classes of the Atom -class. See the atom.h file for a list of methods these classes -defines. The atom style determines what quantities are associated -with an atom in a LAMMPS simulation. If one of the existing atom -styles does not define all the arrays you need to store with an atom, -then a new atom class can be created. +New commands can be added to LAMMPS input scripts by adding new +classes that have a "command" method and are listed in the Command +sections of style.h (or style_user.h). For example, the create_atoms, +read_data, velocity, and run commands are all implemented in this +fashion. When such a command is encountered in the LAMMPS input +script, LAMMPS simply creates a class with the corresponding name, +invokes the "command" method of the class, and passes it the arguments +from the input script. The command method can perform whatever +operations it wishes on LAMMPS data structures. -Atom_atomic.cpp and atom_atomic.h are the simplest example of an Atom -class. They implement the {atomic} style of the -"atom_style"_atom_style.html command. +The single method your new class must define is as follows: -Here is a brief description of the class methods in atom.h: +command: operations performed by the new command :tb(s=:) -copy: copy info for one atom to another atom's array location -pack_comm: store an atom's info in a buffer communicated every timestep -unpack_comm: retrieve an atom's info from the buffer -pack_reverse: store an atom's info in a buffer communicating partial forces -unpack_reverse: retrieve an atom's info from the buffer -pack_border: store an atom's info in a buffer communicated on neighbor re-builds -unpack_border: retrieve an atom's info from the buffer -pack_exchange: store all an atom's info to migrate to another processor -unpack_exchange: retrieve an atom's info from the buffer -:tb(s=:) +Of course, the new class can define other methods and variables as +needed. -There are also several methods in atom.cpp you will need to augment -with information about your new atom class, following the patterns of -the other atom styles. These routines are so similar for all classes, -that it was simpler to just have one master routine for all classes. +:line -constructor: create style variable and atom array ptrs to NULL -destructor: free memory for atom arrays -set_style: set style variable -check_style: check for pure style vs hybrid style -style2arg: convert style variables to keywords -grow: re-allocate atom arrays to longer lengths -unpack_data: parse atom lines from data file -create_one: create an individual atom of this style -size_restart: number of restart quantities associated with proc's atoms -pack_restart: pack atom quantities into a buffer -unpack_restart: unpack atom quantities from a buffer -memory_usage: memory allocated by atom arrays -:tb(s=:) +Kspace computations :link(kspace),h4 + +Classes that compute long-range Coulombic interactions via K-space +represenations (Ewald, PPPM) are derived from the KSpace class. New +styles can be created to add new K-space options to LAMMPS. + +Ewald.cpp is an example of computing K-space interactions. + +Here is a brief description of methods you define in your new derived +class. See kspace.h for details. + +init: initialize the calculation before a run +setup: computation before the 1st timestep of a run +compute: every-timestep computation +memory_usage: tally of memory usage :tb(s=:) + +:line + +Minimization solvers :link(min),h4 + +Classes that perform energy minimization derived from the Min class. +New styles can be created to add new minimization algorithms to +LAMMPS. + +Min_cg.cpp is an example of conjugate gradient minimization. + +Here is a brief description of methods you define in your new derived +class. See min.h for details. + +init: initialize the minimization before a run +run: perform the minimization +memory_usage: tally of memory usage :tb(s=:) + +:line + +Pairwise potentials :link(pair),h4 + +Classes that compute pairwise interactions are derived from the Pair +class. In LAMMPS, pairwise calculation include manybody potentials +such as EAM or Tersoff where particles interact without a static bond +topology. New styles can be created to add new pair potentials to +LAMMPS. + +Pair_lj_cut.cpp is a simple example of a Pair class, though it +includes some optional methods to enable its use with rRESPA. + +Here is a brief description of the class methods in pair.h: + +compute: workhorse routine that computes pairwise interactions +settings: reads the input script line with arguments you define +coeff: set coefficients for one i,j type pair +init_one: perform initialization for one i,j type pair +init_style: initialization specific to this pair style +write & read_restart: write/read i,j pair coeffs to restart files +write & read_restart_settings: write/read global settings to restart files +single: force and energy of a single pairwise interaction between 2 atoms +compute_inner/middle/outer: versions of compute used by rRESPA :tb(s=:) + +The inner/middle/outer routines are optional. + +:line + +Region styles :link(region),h4 + +Classes that define geometric regions are derived from the Region +class. Regions are used elsewhere in LAMMPS to group atoms, delete +atoms to create a void, insert atoms in a specified region, etc. New +styles can be created to add new region shapes to LAMMPS. + +Region_sphere.cpp is an example of a spherical region. + +Here is a brief description of methods you define in your new derived +class. See region.h for details. + +match: determine whether a point is in the region :tb(s=:) + +:line + +Thermodynamic output options :link(thermo),h4 + +There is one class that computes and prints thermodynamic information +to the screen and log file; see the file thermo.cpp. + +There are several styles defined in thermo.cpp: "one", "multi", +"granular", etc. There is also a flexible "custom" style which allows +the user to explicitly list keywords for quantities to print when +thermodynamic info is output. See the +"thermo_style"_thermo_style.html command for a list of defined +quantities. + +The thermo styles (one, multi, etc) are simply lists of keywords. +Adding a new style thus only requies defining a new list of keywords. +Search for the word "customize" with references to "thermo style" in +thermo.cpp to see the two locations where code will need to be added. + +New keywords can also be added to thermo.cpp to compute new quantities +for output. Search for the word "customize" with references to +"keyword" in thermo.cpp to see the several locations where code will +need to be added. + +Note that the "thermo_style custom"_thermo.html command already allows +for thermo output of quantities calculated by "fixes"_fix.html, +"computes"_compute.html, and "variables"_variable.html. Thus, it may +be simpler to compute what you wish via one of those constructs, than +by adding a new keyword to the thermo command. :line Variable options :link(variable),h4 -The variable class stores and evaluates input script variables $a, $b, -... $z, as described in "this section"_Section_commands.html#3_2. -{Equal}-style variables are defined by an equation that is evaluated -each time the variable is used. The equation can include functions, -vectors, keywords, and numbers as described in the -"variable"_variable.html command. The list of valid functions, -vectors, and keywords, can be extended by adding a few lines of code -to the evaluate() method at the end of the variable.cpp file. Search -for the word "customize" to find the correct locations for adding -code. +There is one class that computes and stores "variable"_variable.html +information in LAMMPS; see the file variable.cpp. The value +associated with a variable can be periodically printed to the screen +via the "print"_print.html, "fix print"_fix_print.html, or +"thermo_style custom"_thermo_style.html commands. Variables of style +"equal" can compute complex equations that involve the following types +of arguments: -A new function (e.g. foo(arg1,arg2,...)) can be added in the section -that starts with the comment +thermo keywords = ke, vol, atoms, ... +other variables = v_a, v_myvar, ... +math functions = div(x,y), mult(x,y), add(x,y), ... +group functions = mass(group), xcm(group,x), ... +atom values = x[123], y[3], vx[34], ... +compute values = c_mytemp[0], c_thermo_press[3], ... -// customize by adding function to this list and to if statement :pre +Adding keywords for the "thermo_style custom"_themo_style.html command +(which can then be accessed by variables) was discussed +"here"_Section_modify.html#thermo on this page. -A new vector (e.g. q[]) can be added in the section that starts with -the comment +Adding a new math function of one or two arguments can be done by +editing one section of the Variable::evaulate() method. Search for +the word "customize" to find the appropriate location. -// customize by adding vector to this list and to if statement :pre +Adding a new group function can be done by editing one section of the +Variable::evaulate() method. Search for the word "customize" to find +the appropriate location. You may need to add a new method to the +Group class as well (see the group.cpp file). -A new keyword (e.g. mysum) can be added in the section that starts with -the comment +Accessing a new atom-based vector can be done by editing one section +of the Variable::evaulate() method. Search for the word "customize" +to find the appropriate location. -// customize by adding keyword to this list and to if statement :pre - -Note that keywords supported by the "thermo_style -custom"_themo_style.html command are evaluated by the thermo routines, -so do not need to be added to variable.cpp. +Adding new "compute styles"_compute.html (whose calculated values can +then be accessed by variables) was discussed +"here"_Section_modify.html#compute on this page. :line - -New top-level commands :link(command),h4 - -It is possible to add a new command to a LAMMPS input script as -opposed to adding a new style to an existing command (atom_style, -pair_style, fix, etc). For example the create_atoms, read_data, -velocity, and run commands are all top-level LAMMPS commands that are -listed in the Command section of style.h. When such a command is -encountered in the LAMMPS input script, the topmost level of LAMMPS -(lammps.cpp) simply creates a class with the corresponding name, -invokes the "command" method of the class, and passes it the arguments -from the input script. The command method can perform whatever -operations it wishes on the LAMMPS data structures. - -Thus to add a new command, you simply need to add a *.cpp and *.h file -containing a single class: - -command: operations performed by the new command :tb(s=:) - -Of course, the new class can define other methods and variables that -it uses internally. - :line :link(Foo) diff --git a/doc/Section_start.html b/doc/Section_start.html index d88eb13540..93a186dccc 100644 --- a/doc/Section_start.html +++ b/doc/Section_start.html @@ -16,16 +16,18 @@ new and experienced users.

      2.1 What's in the LAMMPS distribution
      2.2 Making LAMMPS
      -2.3 Running LAMMPS
      -2.4 Command-line options
      -2.5 Screen output
      -2.6 Tips for users of previous versions
      +2.3 Making LAMMPS with optional packages
      +2.4 Building LAMMPS as a library
      +2.5 Running LAMMPS
      +2.6 Command-line options
      +2.7 Screen output
      +2.8 Tips for users of previous versions

      2.1 What's in the LAMMPS distribution

      -

      When you download LAMMPS you will need to unzip and untar the +

      When you download SLAMMPS you will need to unzip and untar the downloaded file with the following commands, after placing the file in an appropriate directory.

      @@ -57,20 +59,19 @@ makefile, there are compiler options, additional libraries can be used (MPI, FFT), etc. Please read this section carefully. If you are not comfortable with makefiles, or building codes on a Unix platform, or running an MPI job on your machine, please find a local expert to help -you. Many of the emails we get about build and run problems are not -really about LAMMPS - they are peculiar to the user's system, -compilers, libraries, etc. Such questions are better answered by a -local expert. +you. Many compiling, linking, and run problems users have do not +really have to do with LAMMPS - they are peculiar to the user's +system, compilers, libraries, etc. Such questions are better answered +by a local expert.

      If you have a build problem that you are convinced is a LAMMPS issue (e.g. the compiler complains about a line of LAMMPS source code), then please send an email to the -developers. Note that doesn't -include linking problems - that's a question for a local expert! +developers.

      -

      Also, if you succeed in building LAMMPS on a new kind of machine -(which there isn't a similar Makefile for in the distribution), send -it to the developers and we'll include it in future LAMMPS releases. +

      If you succeed in building LAMMPS on a new kind of machine (which +there isn't a similar Makefile for in the distribution), send it to +the developers and we'll include it in future LAMMPS releases.

      Building a LAMMPS executable:

      @@ -85,12 +86,9 @@ type a command like: gmake mac

    If you get no errors and an executable like lmp_linux or lmp_mac is -produced, you're done; it's your lucky day. The remainder of this -section addressed the following topics: errors that occur when making -LAMMPS, editing a new low-level Makefile.foo, how to make LAMMPS with -and without packages, and additional build tips. +produced, you're done; it's your lucky day.

    -

    Errors that occur when making LAMMPS: +

    Errors that can occur when making LAMMPS:

    (1) If the make command breaks immediately with errors that indicate it can't find files with a "*" in their names, this can be because @@ -210,98 +208,6 @@ gmake foo

    You should get the executable lmp_foo when the build is complete.

    -

    How to make LAMMPS with and without packages: -

    -

    The source code for LAMMPS is structured as a large set of core files -that are always used plus additional packages, which are groups of -files that enable a specific set of features. For example, force -fields for molecular systems or granular systems are in packages. You -can see the list of packages by typing "make package". The current -list of packages is as follows: -

    -
    - - - - - - - -
    class2 class 2 force fields
    dpd dissipative particle dynamics (DPD) force field
    granular force fields and boundary conditions for granular systems
    kspace long-range Ewald and particle-mesh (PPPM) solvers
    manybody metal, 3-body, bond-order potentials
    molecule force fields for molecular systems
    poems coupled rigid body motion
    xtc dump atom snapshots in XTC format -
    - -

    Any or all of these packages can be included or excluded when LAMMPS -is built. The default is to include only the kspace, manybody, and -molecule packages. You may wish to exclude certain packages if you -will never run certain kinds of simulations. This will produce a -smaller executable which in some cases will also run a bit faster. -

    -

    Packages are included or excluded by typing "make yes-name" or "make -no-name", where "name" is the name of the package. You can also type -"make yes-all" or "make no-all" to include/exclude all optional -packages. These commands work by simply moving files back and forth -between the main src directory and sub-directories with the package -name, so that the files are not seen when LAMMPS is built. After you -have included or excluded a package, you must re-make LAMMPS. -

    -

    Additional make options exist to help manage LAMMPS files that exist -in both the src directory and in package sub-directories. Typing -"make package-update" will overwrite src files with files from the -package directories if the package has been included. Typing "make -package-overwrite" will overwrite files in the package directories -with src files. Typing "make package-check" will list differences -between src and package versions of the same files. -

    -

    To use the poems package you must build LAMMPS with the POEMS library, -which computes the constrained rigid-body motion of articulated -(jointed) multibody systems. POEMS was written and is distributed by -Prof Kurt Anderson's group at Rensselaer Polytechnic Institute (RPI). -It is included in the LAMMPS distribution. To build LAMMPS with -POEMS, you must use a low-level LAMMPS Makefile that includes the -POEMS directory in its paths. See Makefile.g++.poems as an example. -You must also build POEMS itself as a library before building LAMMPS, -so that LAMMPS can link against it. The POEMS library is built by -typing "make" from within the poems directory in the LAMMPS -distribution. By default this uses Makefile which uses the gcc -compiler. If you need to use another compiler (so that the POEMS -library and LAMMPS are consistent), use another poems/Makefile.* or -create your own and invoke it as "make -f Makefile.*". -

    -

    Building LAMMPS as a library: -

    -

    LAMMPS can be built as a library, which can then be called from -another application or a scripting language. See this -section for more info on coupling LAMMPS to -other codes. Building LAMMPS as a library is done by typing -

    -
    make makelib
    -make -f Makefile.lib foo 
    -
    -

    where foo is the machine name. The first "make" command will create a -current Makefile.lib with all the file names in your src dir. The 2nd -"make" command will use it to build LAMMPS as a library. This -requires that Makefile.foo have a library target (lib) and -system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux -for an example. The build will create the file liblmp_foo.a which -another application can link to. The callable functions in the -library are listed in library.h, but you can add as many functions as -you wish to library.h and library.cpp, which can access LAMMPS data -and return it to the caller or set LAMMPS data values as specified by -the caller. These 3 functions are included in the library: -

    -
    void lammps_open(int, char **, MPI_Comm);
    -void lammps_close();
    -int lammps_command(char *); 
    -
    -

    The lammps_open() function is used to initialize LAMMPS, passing in a -list of strings as if they were command-line arguments when -LAMMPS is run from the command line and a MPI communicator for LAMMPS -to run under. The lammps_close() function is used to shut down LAMMPS -and free all its memory. The lammps_command() function is used to -pass a string to LAMMPS as if it were an input command read from an -input script. See the library.h file for more information about the -arguments and return values for these 3 functions. -

    Additional build tips:

    (1) Building LAMMPS for multiple platforms. @@ -337,11 +243,149 @@ make. Or you should be able to pull all the source files into Visual C++ (ugh) or some similar development environment and build it. In the src/MAKE/Windows directory are some notes from users on how they built LAMMPS under Windows, so you can look at their instructions for -tips. Good luck - I can't help you on this one. +tips. Good luck - we can't help you on this one. +

    +

    2.3 Making LAMMPS with optional packages +

    +

    The source code for LAMMPS is structured as a large set of core files +that are always used plus additional packages, which are groups of +files that enable a specific set of features. For example, force +fields for molecular systems or granular systems are in packages. You +can see the list of packages by typing "make package". The current +list of packages is as follows: +

    +
    + + + + + + + + + +
    class2 class 2 force fields
    dpd dissipative particle dynamics (DPD) force field
    granular force fields and boundary conditions for granular systems
    kspace long-range Ewald and particle-mesh (PPPM) solvers
    manybody metal, 3-body, bond-order potentials
    meam modified embedded atom method (MEAM) potential
    molecule force fields for molecular systems
    opt optimized versions of a few pair potentials
    poems coupled rigid body motion
    xtc dump atom snapshots in XTC format +
    + +

    Any or all packages can be included or excluded when LAMMPS is built. +The one exception is that to use the "opt" package, you must also be +using the "molecule" and "manybody" packages. You may wish to exclude +certain packages if you will never run certain kinds of simulations. +This will produce a smaller executable which may run a bit faster. +

    +

    By default, LAMMPS includes only the "kspace", "manybody", and +"molecule" packages. As described below, some packages require LAMMPS +be linked to separately built library files, which will require +editing of your machine Makefile. +

    +

    Packages are included or excluded by typing "make yes-name" or "make +no-name", where "name" is the name of the package. You can also type +"make yes-all" or "make no-all" to include/exclude all optional +packages. These commands work by simply moving files back and forth +between the main src directory and sub-directories with the package +name, so that the files are seen or not seen when LAMMPS is built. +After you have included or excluded a package, you must re-make +LAMMPS. +

    +

    Additional make options exist to help manage LAMMPS files that exist +in both the src directory and in package sub-directories. You do not +normally need to use these commands unless you are editing LAMMPS +files or have downloaded a patch from the LAMMPS WWW site. Typing +"make package-update" will overwrite src files with files from the +package directories if the package has been included. It should be +used after a patch is installed, since patches only update the master +package version of a file. Typing "make package-overwrite" will +overwrite files in the package directories with src files. Typing +"make package-check" will list differences between src and package +versions of the same files. +

    +

    To use the "poems" package you must build LAMMPS with the POEMS +library, which computes the constrained rigid-body motion of +articulated (jointed) multibody systems. POEMS was written and is +distributed by Prof Kurt Anderson's group at Rensselaer Polytechnic +Institute (RPI) and a version is included in the LAMMPS distribution +under the "lib" directory. To build LAMMPS with POEMS, you must use a +low-level LAMMPS Makefile that includes the POEMS directory in its +paths. See Makefile.g++_poems as an example. You must also build +POEMS itself as a library before building LAMMPS, so that LAMMPS can +link against it. The POEMS library is built by typing "make" from +within the poems directory with the appropriate Makefile, e.g. "make +-f Makefile.g++". If one of the provided Makefiles is not appropriate +for your system you can edit or add one as needed. +

    +

    To use the "meam" package you must build LAMMPS with the MEAM library, +which computes the modified embedded atom method potential, which is a +generalization of EAM potentials that can be used to model a wider +variety of materials. This MEAM implementation was written by Greg +Wagner at Sandia and is included under the "lib" directory. To build +LAMMPS with MEAM, you must use a low-level LAMMPS Makefile that +includes the MEAM directory in its paths. See Makefile.linux_meam as +an example. You must also build MEAM itself as a library before +building LAMMPS, so that LAMMPS can link against it. This requires a +F90 compiler. The library is built by typing "make" from within the +meam directory with the appropriate Makefile, e.g. "make -f +Makefile.icc". If one of the provided Makefiles is not appropriate +for your system you can edit or add one as needed. +

    +

    Linking a Fortran library to a C++ code can be problematic +(e.g. non-matching underscore conventions). If you have problems with +a particular compiler/machine, please send an email to the developers. +

    +

    2.4 Building LAMMPS as a library +

    +

    LAMMPS can be built as a library, which can then be called from +another application or a scripting language. See this +section for more info on coupling LAMMPS to +other codes. Building LAMMPS as a library is done by typing +

    +
    make makelib
    +make -f Makefile.lib foo 
    +
    +

    where foo is the machine name. The first "make" command will create a +current Makefile.lib with all the file names in your src dir. The 2nd +"make" command will use it to build LAMMPS as a library. This +requires that Makefile.foo have a library target (lib) and +system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux +for an example. The build will create the file liblmp_foo.a which +another application can link to. +

    +

    When used from a C++ program, the library allows one or more LAMMPS +objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS +namespace; you can safely use any of its classes and methods from +within your application code, as needed. See the sample code +examples/couple/c++_driver.cpp as an example. +

    +

    When used from a C or Fortran program or a scripting language, the +library has a simple function-style interface, provided in library.cpp +and library.h. See the sample code examples/couple/c_driver.cpp as an +example. +

    +

    You can add as many functions as you wish to library.cpp and +library.h. In a general sense, those functions can access LAMMPS data +and return it to the caller or set LAMMPS data values as specified by +the caller. These 4 functions are currently included in library.cpp: +

    +
    void lammps_open(int, char **, MPI_Comm, void **ptr);
    +void lammps_close(void *ptr);
    +int lammps_file(void *ptr, char *);
    +int lammps_command(void *ptr, char *); 
    +
    +

    The lammps_open() function is used to initialize LAMMPS, passing in a +list of strings as if they were command-line arguments when +LAMMPS is run from the command line and a MPI communicator for LAMMPS +to run under. It returns a ptr to the LAMMPS object that is created, +and which should be used in subsequent library calls. Note that +lammps_open() can be called multiple times to create multiple LAMMPS +objects. +

    +

    The lammps_close() function is used to shut down LAMMPS and free all +its memory. The lammps_file() and lammps_command() functions are used +to pass a file or string to LAMMPS as if it were an input file or +single command read from an input script.


    -

    2.3 Running LAMMPS +

    2.5 Running LAMMPS

    By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux < in.file. This means you first create an input script (e.g. in.file) @@ -388,7 +432,7 @@ more processors or setup a smaller problem.


    -

    2.4 Command-line options +

    2.6 Command-line options

    At run time, LAMMPS recognizes several optional command-line switches which may be used in any order. For example, lmp_ibm might be @@ -476,7 +520,7 @@ variables in scripts.


    -

    2.5 LAMMPS screen output +

    2.7 LAMMPS screen output

    As LAMMPS reads an input script, it prints information to both the screen and a log file about significant actions it takes to setup a @@ -573,7 +617,7 @@ communication, roughly 75% in the example above.


    -

    2.6 Tips for users of previous LAMMPS versions +

    2.8 Tips for users of previous LAMMPS versions

    LAMMPS 2003 is a complete C++ rewrite of LAMMPS 2001, which was written in F90. Features of earlier versions of LAMMPS are listed in diff --git a/doc/Section_start.txt b/doc/Section_start.txt index d84f7592c2..a3a98e508b 100644 --- a/doc/Section_start.txt +++ b/doc/Section_start.txt @@ -13,16 +13,18 @@ new and experienced users. 2.1 "What's in the LAMMPS distribution"_#2_1 2.2 "Making LAMMPS"_#2_2 -2.3 "Running LAMMPS"_#2_3 -2.4 "Command-line options"_#2_4 -2.5 "Screen output"_#2_5 -2.6 "Tips for users of previous versions"_#2_6 :all(b) +2.3 "Making LAMMPS with optional packages"_#2_3 +2.4 "Building LAMMPS as a library"_#2_4 +2.5 "Running LAMMPS"_#2_5 +2.6 "Command-line options"_#2_6 +2.7 "Screen output"_#2_7 +2.8 "Tips for users of previous versions"_#2_8 :all(b) :line 2.1 What's in the LAMMPS distribution :h4,link(2_1) -When you download LAMMPS you will need to unzip and untar the +When you download SLAMMPS you will need to unzip and untar the downloaded file with the following commands, after placing the file in an appropriate directory. @@ -52,20 +54,19 @@ makefile, there are compiler options, additional libraries can be used (MPI, FFT), etc. Please read this section carefully. If you are not comfortable with makefiles, or building codes on a Unix platform, or running an MPI job on your machine, please find a local expert to help -you. Many of the emails we get about build and run problems are not -really about LAMMPS - they are peculiar to the user's system, -compilers, libraries, etc. Such questions are better answered by a -local expert. +you. Many compiling, linking, and run problems users have do not +really have to do with LAMMPS - they are peculiar to the user's +system, compilers, libraries, etc. Such questions are better answered +by a local expert. If you have a build problem that you are convinced is a LAMMPS issue (e.g. the compiler complains about a line of LAMMPS source code), then please send an email to the -"developers"_http://lammps.sandia.gov/authors.html. Note that doesn't -include linking problems - that's a question for a local expert! +"developers"_http://lammps.sandia.gov/authors.html. -Also, if you succeed in building LAMMPS on a new kind of machine -(which there isn't a similar Makefile for in the distribution), send -it to the developers and we'll include it in future LAMMPS releases. +If you succeed in building LAMMPS on a new kind of machine (which +there isn't a similar Makefile for in the distribution), send it to +the developers and we'll include it in future LAMMPS releases. [{Building a LAMMPS executable:}] @@ -80,12 +81,9 @@ make linux gmake mac :pre If you get no errors and an executable like lmp_linux or lmp_mac is -produced, you're done; it's your lucky day. The remainder of this -section addressed the following topics: errors that occur when making -LAMMPS, editing a new low-level Makefile.foo, how to make LAMMPS with -and without packages, and additional build tips. +produced, you're done; it's your lucky day. -[{Errors that occur when making LAMMPS:}] +[{Errors that can occur when making LAMMPS:}] (1) If the make command breaks immediately with errors that indicate it can't find files with a "*" in their names, this can be because @@ -205,96 +203,6 @@ gmake foo :pre You should get the executable lmp_foo when the build is complete. -[{How to make LAMMPS with and without packages:}] - -The source code for LAMMPS is structured as a large set of core files -that are always used plus additional packages, which are groups of -files that enable a specific set of features. For example, force -fields for molecular systems or granular systems are in packages. You -can see the list of packages by typing "make package". The current -list of packages is as follows: - -class2 : class 2 force fields -dpd : dissipative particle dynamics (DPD) force field -granular : force fields and boundary conditions for granular systems -kspace : long-range Ewald and particle-mesh (PPPM) solvers -manybody : metal, 3-body, bond-order potentials -molecule : force fields for molecular systems -poems : coupled rigid body motion -xtc : dump atom snapshots in XTC format :tb(s=:) - -Any or all of these packages can be included or excluded when LAMMPS -is built. The default is to include only the kspace, manybody, and -molecule packages. You may wish to exclude certain packages if you -will never run certain kinds of simulations. This will produce a -smaller executable which in some cases will also run a bit faster. - -Packages are included or excluded by typing "make yes-name" or "make -no-name", where "name" is the name of the package. You can also type -"make yes-all" or "make no-all" to include/exclude all optional -packages. These commands work by simply moving files back and forth -between the main src directory and sub-directories with the package -name, so that the files are not seen when LAMMPS is built. After you -have included or excluded a package, you must re-make LAMMPS. - -Additional make options exist to help manage LAMMPS files that exist -in both the src directory and in package sub-directories. Typing -"make package-update" will overwrite src files with files from the -package directories if the package has been included. Typing "make -package-overwrite" will overwrite files in the package directories -with src files. Typing "make package-check" will list differences -between src and package versions of the same files. - -To use the poems package you must build LAMMPS with the POEMS library, -which computes the constrained rigid-body motion of articulated -(jointed) multibody systems. POEMS was written and is distributed by -Prof Kurt Anderson's group at Rensselaer Polytechnic Institute (RPI). -It is included in the LAMMPS distribution. To build LAMMPS with -POEMS, you must use a low-level LAMMPS Makefile that includes the -POEMS directory in its paths. See Makefile.g++.poems as an example. -You must also build POEMS itself as a library before building LAMMPS, -so that LAMMPS can link against it. The POEMS library is built by -typing "make" from within the poems directory in the LAMMPS -distribution. By default this uses Makefile which uses the gcc -compiler. If you need to use another compiler (so that the POEMS -library and LAMMPS are consistent), use another poems/Makefile.* or -create your own and invoke it as "make -f Makefile.*". - -[{Building LAMMPS as a library:}] - -LAMMPS can be built as a library, which can then be called from -another application or a scripting language. See "this -section"_Section_howto.html#4_10 for more info on coupling LAMMPS to -other codes. Building LAMMPS as a library is done by typing - -make makelib -make -f Makefile.lib foo :pre - -where foo is the machine name. The first "make" command will create a -current Makefile.lib with all the file names in your src dir. The 2nd -"make" command will use it to build LAMMPS as a library. This -requires that Makefile.foo have a library target (lib) and -system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux -for an example. The build will create the file liblmp_foo.a which -another application can link to. The callable functions in the -library are listed in library.h, but you can add as many functions as -you wish to library.h and library.cpp, which can access LAMMPS data -and return it to the caller or set LAMMPS data values as specified by -the caller. These 3 functions are included in the library: - -void lammps_open(int, char **, MPI_Comm); -void lammps_close(); -int lammps_command(char *); :pre - -The lammps_open() function is used to initialize LAMMPS, passing in a -list of strings as if they were "command-line arguments"_#2_4 when -LAMMPS is run from the command line and a MPI communicator for LAMMPS -to run under. The lammps_close() function is used to shut down LAMMPS -and free all its memory. The lammps_command() function is used to -pass a string to LAMMPS as if it were an input command read from an -input script. See the library.h file for more information about the -arguments and return values for these 3 functions. - [{Additional build tips:}] (1) Building LAMMPS for multiple platforms. @@ -330,11 +238,147 @@ make. Or you should be able to pull all the source files into Visual C++ (ugh) or some similar development environment and build it. In the src/MAKE/Windows directory are some notes from users on how they built LAMMPS under Windows, so you can look at their instructions for -tips. Good luck - I can't help you on this one. +tips. Good luck - we can't help you on this one. + +2.3 Making LAMMPS with optional packages :h4,link(2_3) + +The source code for LAMMPS is structured as a large set of core files +that are always used plus additional packages, which are groups of +files that enable a specific set of features. For example, force +fields for molecular systems or granular systems are in packages. You +can see the list of packages by typing "make package". The current +list of packages is as follows: + +class2 : class 2 force fields +dpd : dissipative particle dynamics (DPD) force field +granular : force fields and boundary conditions for granular systems +kspace : long-range Ewald and particle-mesh (PPPM) solvers +manybody : metal, 3-body, bond-order potentials +meam : modified embedded atom method (MEAM) potential +molecule : force fields for molecular systems +opt : optimized versions of a few pair potentials +poems : coupled rigid body motion +xtc : dump atom snapshots in XTC format :tb(s=:) + +Any or all packages can be included or excluded when LAMMPS is built. +The one exception is that to use the "opt" package, you must also be +using the "molecule" and "manybody" packages. You may wish to exclude +certain packages if you will never run certain kinds of simulations. +This will produce a smaller executable which may run a bit faster. + +By default, LAMMPS includes only the "kspace", "manybody", and +"molecule" packages. As described below, some packages require LAMMPS +be linked to separately built library files, which will require +editing of your machine Makefile. + +Packages are included or excluded by typing "make yes-name" or "make +no-name", where "name" is the name of the package. You can also type +"make yes-all" or "make no-all" to include/exclude all optional +packages. These commands work by simply moving files back and forth +between the main src directory and sub-directories with the package +name, so that the files are seen or not seen when LAMMPS is built. +After you have included or excluded a package, you must re-make +LAMMPS. + +Additional make options exist to help manage LAMMPS files that exist +in both the src directory and in package sub-directories. You do not +normally need to use these commands unless you are editing LAMMPS +files or have downloaded a patch from the LAMMPS WWW site. Typing +"make package-update" will overwrite src files with files from the +package directories if the package has been included. It should be +used after a patch is installed, since patches only update the master +package version of a file. Typing "make package-overwrite" will +overwrite files in the package directories with src files. Typing +"make package-check" will list differences between src and package +versions of the same files. + +To use the "poems" package you must build LAMMPS with the POEMS +library, which computes the constrained rigid-body motion of +articulated (jointed) multibody systems. POEMS was written and is +distributed by Prof Kurt Anderson's group at Rensselaer Polytechnic +Institute (RPI) and a version is included in the LAMMPS distribution +under the "lib" directory. To build LAMMPS with POEMS, you must use a +low-level LAMMPS Makefile that includes the POEMS directory in its +paths. See Makefile.g++_poems as an example. You must also build +POEMS itself as a library before building LAMMPS, so that LAMMPS can +link against it. The POEMS library is built by typing "make" from +within the poems directory with the appropriate Makefile, e.g. "make +-f Makefile.g++". If one of the provided Makefiles is not appropriate +for your system you can edit or add one as needed. + +To use the "meam" package you must build LAMMPS with the MEAM library, +which computes the modified embedded atom method potential, which is a +generalization of EAM potentials that can be used to model a wider +variety of materials. This MEAM implementation was written by Greg +Wagner at Sandia and is included under the "lib" directory. To build +LAMMPS with MEAM, you must use a low-level LAMMPS Makefile that +includes the MEAM directory in its paths. See Makefile.linux_meam as +an example. You must also build MEAM itself as a library before +building LAMMPS, so that LAMMPS can link against it. This requires a +F90 compiler. The library is built by typing "make" from within the +meam directory with the appropriate Makefile, e.g. "make -f +Makefile.icc". If one of the provided Makefiles is not appropriate +for your system you can edit or add one as needed. + +Linking a Fortran library to a C++ code can be problematic +(e.g. non-matching underscore conventions). If you have problems with +a particular compiler/machine, please send an email to the developers. + +2.4 Building LAMMPS as a library :h4,link(2_4) + +LAMMPS can be built as a library, which can then be called from +another application or a scripting language. See "this +section"_Section_howto.html#4_10 for more info on coupling LAMMPS to +other codes. Building LAMMPS as a library is done by typing + +make makelib +make -f Makefile.lib foo :pre + +where foo is the machine name. The first "make" command will create a +current Makefile.lib with all the file names in your src dir. The 2nd +"make" command will use it to build LAMMPS as a library. This +requires that Makefile.foo have a library target (lib) and +system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux +for an example. The build will create the file liblmp_foo.a which +another application can link to. + +When used from a C++ program, the library allows one or more LAMMPS +objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS +namespace; you can safely use any of its classes and methods from +within your application code, as needed. See the sample code +examples/couple/c++_driver.cpp as an example. + +When used from a C or Fortran program or a scripting language, the +library has a simple function-style interface, provided in library.cpp +and library.h. See the sample code examples/couple/c_driver.cpp as an +example. + +You can add as many functions as you wish to library.cpp and +library.h. In a general sense, those functions can access LAMMPS data +and return it to the caller or set LAMMPS data values as specified by +the caller. These 4 functions are currently included in library.cpp: + +void lammps_open(int, char **, MPI_Comm, void **ptr); +void lammps_close(void *ptr); +int lammps_file(void *ptr, char *); +int lammps_command(void *ptr, char *); :pre + +The lammps_open() function is used to initialize LAMMPS, passing in a +list of strings as if they were "command-line arguments"_#2_6 when +LAMMPS is run from the command line and a MPI communicator for LAMMPS +to run under. It returns a ptr to the LAMMPS object that is created, +and which should be used in subsequent library calls. Note that +lammps_open() can be called multiple times to create multiple LAMMPS +objects. + +The lammps_close() function is used to shut down LAMMPS and free all +its memory. The lammps_file() and lammps_command() functions are used +to pass a file or string to LAMMPS as if it were an input file or +single command read from an input script. :line -2.3 Running LAMMPS :h4,link(2_3) +2.5 Running LAMMPS :h4,link(2_5) By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux < in.file. This means you first create an input script (e.g. in.file) @@ -381,7 +425,7 @@ more processors or setup a smaller problem. :line -2.4 Command-line options :h4,link(2_4) +2.6 Command-line options :h4,link(2_6) At run time, LAMMPS recognizes several optional command-line switches which may be used in any order. For example, lmp_ibm might be @@ -469,7 +513,7 @@ variables in scripts. :line -2.5 LAMMPS screen output :h4,link(2_5) +2.7 LAMMPS screen output :h4,link(2_7) As LAMMPS reads an input script, it prints information to both the screen and a log file about significant actions it takes to setup a @@ -566,7 +610,7 @@ communication, roughly 75% in the example above. :line -2.6 Tips for users of previous LAMMPS versions :h4,link(2_6) +2.8 Tips for users of previous LAMMPS versions :h4,link(2_8) LAMMPS 2003 is a complete C++ rewrite of LAMMPS 2001, which was written in F90. Features of earlier versions of LAMMPS are listed in diff --git a/doc/angle_coeff.html b/doc/angle_coeff.html index a268f46e9f..7b6fbe62ec 100644 --- a/doc/angle_coeff.html +++ b/doc/angle_coeff.html @@ -62,14 +62,14 @@ corresponds to the 1st example above would be listed as the style to display the formula it computes and coefficients specified by the associated angle_coeff command:

    -