Syntax: +
+fix ID group-ID gcmc N X M type seed T mu displace keyword values ... ++
keyword = molecule + molecule value = no or yes ++ +
Examples: +
+fix 2 all gcmc 10 1000 1000 2 29494 298.0 -0.5 0.01 +fix 3 all gcmc 10 100 100 1 3456543 3.0 -2.5 0.1 molecule yes ++
Description: +
+This fix performs grand canonical Monte Carlo (GCMC) exchanges of +particles of the given type with an imaginary ideal gas reservoir at +the specified T and chemical potential (mu) as discussed in +(Frenkel). If used with the fix nvt command, +simulations in the grand canonical enemble (muVT, constant chemical +potential, constant volume, and constant temperature) can be +performed. Specific uses include computing isotherms in microporous +materials, or computing vapor-liquid coexistence curves. +
+Perform up to X exchanges of particles of the given type between the +simulation domain and the imaginary reservoir every N timesteps. Also +perform M Monte Carlo displacements of particles of the given type +within the simulation domain. M should typically be chosen to be +approximately equal to the expected number of particles of the given +type within the domain, which will result in roughly one MC +translation per particle per MC cycle. +
+This fix cannot be used to perform MC displacements of particles other +than the exchanged type. All particles in the simulation domain can be +moved using regular time integration displacements, e.g. via +fix_nvt, resulting in a hybrid GCMC+MD simulation. +
+If used with fix_nvt, the temperature of the imaginary +reservoir, T, should be set to be equivalent to the target temperature +used in fix_nvt. Otherwise, the imaginary reservoir +will not be in thermal equilibrium with the simulation domain. +
+Note that neighbor lists are re-built every timestep that this fix is +invoked, so you should not set N to be too small. However, periodic +rebuilds are necessary in order to avoid dangerous rebuilds and missed +interactions. Specifically, avoid performing so many MC displacements +per timestep that a particle can move beyond the neighbor list skin +distance. See the neighbor command for details. +
+When a particle is to be inserted, its coordinates are chosen as a +random position within the current simulation domain, and its velocity +is randomly chosen from the specified temperature distribution given +by T. +
+Exchanged particles have the specified atom type and are assigned to +two groups: the default group "all" and the group specified in the fix +gcmc command (which can also be "all"). +
+If the setting for the molecule keyword is no, then only single +atoms are exchanged. In this case, you should ensure you do not +delete only a portion of a molecule (only some of its atoms), or +LAMMPS will soon generate an error when it tries to find those atoms. +LAMMPS will warn you if any of the atoms eligible for deletion have a +non-zero molecule ID, but does not check for this at the time of +deletion. +
+If the setting for the molecule keyword is yes, entire molecules +are exchanged. This feature is not yet supported. +
+Use of this fix typically will cause the number of atoms to fluctuate, +therefore, you will want to use the +compute_modify command to insure that the +current number of atoms is used as a normalizing factor each time +temperature is computed. Here is the necessary command: +
+compute_modify thermo_temp dynamic yes ++
If LJ units are used, note that a value of 0.18292026 is used by this +fix as the reduced value for Planck's constant. This value was +derived from LJ paramters for argon, where h* = h/sqrt(sigma^2 * +epsilon * mass), sigma = 3.429 angstroms, epsilon/k = 121.85 K, and +mass = 39.948 amu. +
+Restart, fix_modify, output, run start/stop, minimize info: +
+This fix writes the state of the deposition to binary restart +files. This includes information about the random +number generator seed, the next timestep for MC exchanges, etc. See +the read_restart command for info on how to +re-specify a fix in an input script that reads a restart file, so that +the operation of the fix continues in an uninterrupted fashion. +
+None of the fix_modify options are relevant to this +fix. +
+This fix computes a global vector of length 6, which can be accessed +by various output commands. The vector +values are the following global cummulative quantities: +
+The vector values calculated by this fix are "extensive". +
+No parameter of this fix can be used with the start/stop keywords of +the run command. This fix is not invoked during energy +minimization. +
+Restrictions: +
+This fix is part of the "mc" package. It is only enabled if LAMMPS +was built with that package. See the Making +LAMMPS section for more info. +
+Do not set "neigh_modify once yes" or else this fix will never be +called. Reneighboring is required. +
+You cannot currently exchange charged particles or molecules with a +net charge. +
+Only pairwise interactions, as defined by the +pair_style command, are included in this +calculation. Long-range interactions due to a +kspace_style command are not included. Not all +pair potentials can be evaluated in a pairwise mode as required by +this fix. For example, 3-body potentials, such as +Tersoff and Stillinger-Weber cannot +be used. EAM potentials for metals only include the +pair potential portion of the EAM interaction, not the embedding term. +
+Related commands: +
+fix_nvt, neighbor, +fix_deposit, fix_evaporate +
+Default: +
+The option defaults are molecule = no. +
+(Frenkel) Frenkel and Smit, Understanding Molecular Simulation, +Academic Press, London, 2002. +
+ diff --git a/doc/fix_gcmc.txt b/doc/fix_gcmc.txt new file mode 100644 index 0000000000..d2c810f4bf --- /dev/null +++ b/doc/fix_gcmc.txt @@ -0,0 +1,169 @@ +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +fix gcmc command :h3 + +[Syntax:] + +fix ID group-ID gcmc N X M type seed T mu displace keyword values ... :pre + +ID, group-ID are documented in "fix"_fix.html command :ulb,l +gcmc = style name of this fix command :l +N = invoke this fix every N steps :l +X = number of exchanges to attempt every N steps :l +M = number of MC displacements to attempt every N steps :l +type = atom type of exchanged particles :l +seed = random # seed (positive integer) :l +T = temperature of the ideal gas reservoir (temperature units) :l +mu = chemical potential of the ideal gas reservoir (energy units) :l +displace = maximum Monte Carlo displacement distance (length units) :l +zero or more keyword/value pairs may be appended to args :l +keyword = {molecule} + {molecule} value = {no} or {yes} :pre +:ule + +[Examples:] + +fix 2 all gcmc 10 1000 1000 2 29494 298.0 -0.5 0.01 +fix 3 all gcmc 10 100 100 1 3456543 3.0 -2.5 0.1 molecule yes :pre + +[Description:] + +This fix performs grand canonical Monte Carlo (GCMC) exchanges of +particles of the given type with an imaginary ideal gas reservoir at +the specified T and chemical potential (mu) as discussed in +"(Frenkel)"_#Frenkel. If used with the "fix nvt"_fix_nh.html command, +simulations in the grand canonical enemble (muVT, constant chemical +potential, constant volume, and constant temperature) can be +performed. Specific uses include computing isotherms in microporous +materials, or computing vapor-liquid coexistence curves. + +Perform up to X exchanges of particles of the given type between the +simulation domain and the imaginary reservoir every N timesteps. Also +perform M Monte Carlo displacements of particles of the given type +within the simulation domain. M should typically be chosen to be +approximately equal to the expected number of particles of the given +type within the domain, which will result in roughly one MC +translation per particle per MC cycle. + +This fix cannot be used to perform MC displacements of particles other +than the exchanged type. All particles in the simulation domain can be +moved using regular time integration displacements, e.g. via +"fix_nvt"_fix_nvt.html, resulting in a hybrid GCMC+MD simulation. + +If used with "fix_nvt"_fix_nvt.html, the temperature of the imaginary +reservoir, T, should be set to be equivalent to the target temperature +used in "fix_nvt"_fix_nvt.html. Otherwise, the imaginary reservoir +will not be in thermal equilibrium with the simulation domain. + +Note that neighbor lists are re-built every timestep that this fix is +invoked, so you should not set N to be too small. However, periodic +rebuilds are necessary in order to avoid dangerous rebuilds and missed +interactions. Specifically, avoid performing so many MC displacements +per timestep that a particle can move beyond the neighbor list skin +distance. See the "neighbor"_neighbor.html command for details. + +When a particle is to be inserted, its coordinates are chosen as a +random position within the current simulation domain, and its velocity +is randomly chosen from the specified temperature distribution given +by T. + +Exchanged particles have the specified atom type and are assigned to +two groups: the default group "all" and the group specified in the fix +gcmc command (which can also be "all"). + +If the setting for the {molecule} keyword is {no}, then only single +atoms are exchanged. In this case, you should ensure you do not +delete only a portion of a molecule (only some of its atoms), or +LAMMPS will soon generate an error when it tries to find those atoms. +LAMMPS will warn you if any of the atoms eligible for deletion have a +non-zero molecule ID, but does not check for this at the time of +deletion. + +If the setting for the {molecule} keyword is {yes}, entire molecules +are exchanged. This feature is not yet supported. + +Use of this fix typically will cause the number of atoms to fluctuate, +therefore, you will want to use the +"compute_modify"_compute_modify.html command to insure that the +current number of atoms is used as a normalizing factor each time +temperature is computed. Here is the necessary command: + +compute_modify thermo_temp dynamic yes :pre + +If LJ units are used, note that a value of 0.18292026 is used by this +fix as the reduced value for Planck's constant. This value was +derived from LJ paramters for argon, where h* = h/sqrt(sigma^2 * +epsilon * mass), sigma = 3.429 angstroms, epsilon/k = 121.85 K, and +mass = 39.948 amu. + +[Restart, fix_modify, output, run start/stop, minimize info:] + +This fix writes the state of the deposition to "binary restart +files"_restart.html. This includes information about the random +number generator seed, the next timestep for MC exchanges, etc. See +the "read_restart"_read_restart.html command for info on how to +re-specify a fix in an input script that reads a restart file, so that +the operation of the fix continues in an uninterrupted fashion. + +None of the "fix_modify"_fix_modify.html options are relevant to this +fix. + +This fix computes a global vector of length 6, which can be accessed +by various "output commands"_Section_howto.html#4_15. The vector +values are the following global cummulative quantities: + +1 = displacement attempts +2 = displacement successes +3 = deletion attempts +4 = deletion successes +5 = insertion attempts +6 = insertion successes :ul + +The vector values calculated by this fix are "extensive". + +No parameter of this fix can be used with the {start/stop} keywords of +the "run"_run.html command. This fix is not invoked during "energy +minimization"_minimize.html. + +[Restrictions:] + +This fix is part of the "mc" package. It is only enabled if LAMMPS +was built with that package. See the "Making +LAMMPS"_Section_start.html#2_3 section for more info. + +Do not set "neigh_modify once yes" or else this fix will never be +called. Reneighboring is required. + +You cannot currently exchange charged particles or molecules with a +net charge. + +Only pairwise interactions, as defined by the +"pair_style"_pair_style.html command, are included in this +calculation. Long-range interactions due to a +"kspace_style"_kspace_style.html command are not included. Not all +pair potentials can be evaluated in a pairwise mode as required by +this fix. For example, 3-body potentials, such as +"Tersoff"_pair_tersoff.html and "Stillinger-Weber"_pair_sw.html cannot +be used. "EAM"_pair_eam.html potentials for metals only include the +pair potential portion of the EAM interaction, not the embedding term. + +[Related commands:] + +"fix_nvt"_fix_nvt.html, "neighbor"_neighbor.html, +"fix_deposit"_fix_deposit.html, "fix_evaporate"_fix_evaporate.html + +[Default:] + +The option defaults are molecule = no. + +:line + +:link(Frenkel) +[(Frenkel)] Frenkel and Smit, Understanding Molecular Simulation, +Academic Press, London, 2002.