diff --git a/docs/make.jl b/docs/make.jl index a9ab27b..5eb73b5 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,7 +7,7 @@ molecule_subsection_acids = ["systems/2026-methanesulfonicacid.md"] molecule_subsection_thiols = ["systems/2026-diethylsulfide.md", "systems/2026-diisopropylsulfide.md", "systems/2026-dipropylsulfide.md"] molecule_subsections_cyclic = ["systems/2026-aniline.md", "systems/2026-pyridine.md", "systems/2026-pyrrole.md"] surface_subsection = ["systems/2026-Cu.md", "systems/2026-SiO2.md"] -tutorial_subsection = ["tutorials/01-adsorption-stochastics.md", "tutorials/02-benchmarks.md", "tutorials/03-multiple-adsorbates.md", "tutorials/04-multiple-grids.md", "tutorials/05-events-rotations.md", "tutorials/06-events-diffusions.md", "tutorials/07-events-conformer-changes.md", "tutorials/08-events-conversions.md", "tutorials/09-hdf5.md"] +tutorial_subsection = ["tutorials/01-adsorption-stochastics.md", "tutorials/02-benchmarks.md", "tutorials/03-multiple-adsorbates.md", "tutorials/04-multiple-grids.md", "tutorials/05-events-rotations.md", "tutorials/06-events-diffusions.md", "tutorials/07-events-conformer-changes.md", "tutorials/08-events-conversions.md", "tutorials/09-hdf5.md", "tutorials/10-restarting.md"] # Local non-ideal solution #makedocs(sitename="RSA.jl", remotes=nothing, diff --git a/docs/src/developers.md b/docs/src/developers.md index 391ce2c..e4a0dab 100644 --- a/docs/src/developers.md +++ b/docs/src/developers.md @@ -1,7 +1,20 @@ # Developers + +## Testsuit +The RSA package is shipped with some tests for the most important parts of the code. Tests can be run via Pkg or by running the `runtest.jl` file within the test folder. It is also possible to run some test individually. + +* `rsa_tests.jl` + + Running some of the tutorials to ensure that the output of the RSA simulations is correct. + +* `io_tests.jl` + + Reading input files (normal and hdf5) to check that the main input information (molecules, grids, lattice, events) are generated correctly. + !!! info - ... to be done ... + The test suit is fixing the random seed to ensure that an identical result is obtained in every run. Any changes to how random numbers are generated - especially by Random.jl - might results in all tests failing. In this case tests have to be performed with an older version of Random.jl or manually updated to a newer Version. + ## Complete List of Documented Functions and Types ```@autodocs diff --git a/docs/src/events.md b/docs/src/events.md index fab3253..9aefb86 100644 --- a/docs/src/events.md +++ b/docs/src/events.md @@ -9,6 +9,10 @@ Events [Block-Keyword] coverageconvergence [Integer-Keyword] forceadsorption [Integer-Keyword] overlap [Text-Keyword] + + restart [Integer-Keyword] + restartruns [Text-Keyword] + restartfile [Text-Keyword] eventlist [Block-Keyword] ... one event per line @@ -37,6 +41,18 @@ The following list states all keywords of the events block with their default va + `2D` : The van der Waals spheres of the atoms are projected in two dimensions to judge the overlap between adsorbates. This is the default approach in most RSA simulations. + `3D` : The overlap between the van der Waals spheres of the atoms is tested in three dimensions. This setting can only be used in case all coordinates (molecules, lattice, grids) are stated with three dimensions. +* `restart = 0` + + This keyword indicates whether RSA simulations should be performed starting with a provided seed (`restart > 0`). With this keyword the set - also called generation - of RSA simulations to be used is selected. The generation used to create the initial HDF5 file is the 1st generation while each restart based on this HDF5 file is labeled as 2nd, 3rd, etc generation. + +* `restartruns = ...` + + No default value defined. With this keyword the individual RSA simulations within a generation are selected. The numbers of the individual runs must be separated by spaces. For each selected simulation, the user requested number of new restart runs will be performed. + +* `restartfile = ...` + + No default value defined. For restart calculations the HDF5 file of the previous calculation must be provided. The absolut path to this file is stated with this keyword. + * `eventlist ... end` This block keyword is used to define all possible events in the RSA simulation. To define events the labels of the molecules and grids are used. In addition, every event contains a "weight" to balance the likelyhood of certain events to each other. Every line states one event. diff --git a/docs/src/index.md b/docs/src/index.md index 0ba9182..f36634a 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -4,7 +4,7 @@ A *Random Sequential Adsorption (RSA)* package for the modelling of molecular ad ## Features * Random adsorption of adsorbates on a surface grid -* Support of multiple adsorbates and surface grids +* Support of multiple adsorbates and surface grids (both simultanously & sequentially) * Support of diffusion and rotation events * Support of adsorbate conversion events * Analysis of surface coverage and effective gap size diff --git a/docs/src/install.md b/docs/src/install.md index ccff580..abcbf21 100644 --- a/docs/src/install.md +++ b/docs/src/install.md @@ -28,7 +28,7 @@ Pkg.activate() ``` ## Using the RSA package -You can use the RSA package in any of your scripts without activating the project (this would only be necessary if you want to contribute to the development of the package). Simply add the package directory to the *LOAD_PATH*: +You can use the RSA package in any of your scripts by adding the package directory to the *LOAD_PATH*: ``` push!(LOAD_PATH,"/PATH/to/source/code/RSA") using RSA @@ -36,4 +36,9 @@ using RSA To test whether the module was loaded you can use the following command in the Julia REPL: ``` ?RSA +``` +As alternative, you can register the package with the package manager. That step would only be necessary the first time you want to use the RSA package. +``` +using Pkg +Pkg.develop(path="/Path/to/RSA") ``` \ No newline at end of file diff --git a/docs/src/rsa.md b/docs/src/rsa.md index ded20d1..cfb6f27 100644 --- a/docs/src/rsa.md +++ b/docs/src/rsa.md @@ -1,7 +1,7 @@ # About RSA As the name indicates *random sequential adsorption* or simply *RSA* simulations are mainly used to model adsorption events whereby the behaviour of the adsorbates is assumed to be random. This is a crude approximation but still somewhat valid for weakly interacting adsorbates. -Within the area-selective deposition, a core research question is to judge how well a surface - usualle called the *non-growth surface* - can be shielded or blocked by an adsorbate. Here, RSA simulations can help to derive an model for the blocking layer formed by the adsorbates. Furthermore, a first guess of how large the remaining gaps are can be derived. +Within the area-selective deposition, a core research question is to judge how well a surface - usualle called the *non-growth surface* - can be shielded or blocked by an adsorbate. Here, RSA simulations can help to derive a model for the blocking layer formed by the adsorbates. Furthermore, a first guess of how large the remaining gaps are can be derived. In addition to the presence of adsorption events, this RSA package also includes the possibility of rotation, diffusion, and conversion events. Thereby, the present algorithm is slightly moving in the direction of a light version of a kinetic Monte-Carlo (kMC) algorithm. diff --git a/docs/src/run.md b/docs/src/run.md index 8791ad8..8fc47d9 100644 --- a/docs/src/run.md +++ b/docs/src/run.md @@ -18,12 +18,6 @@ savefig(myplot, "RSA_run_352.png") ``` Default functions for plotting RSA runs, evaluating the covered area, and calculating the effective gap size are provided in the [Analysis](@ref) section. -## Using Multithreading with VSCode -Running RSA simulations over VSCode in parallel is possible by changing the "julia.NumThreads" setting. Simply search for "num thread" in the settings searchbar and change to your needs. -To test the new settings use the following command in your notebook: -``` -Threads.nthreads() -``` ## Exported Functions @@ -40,6 +34,8 @@ plot_single_molecule animate_RSA_run plot_count_area_histograms plot_effective_gap_size +plot_count_area_convergence +plot_single_run_convergence ``` ## Datastructure diff --git a/docs/src/tutorials/01-adsorption-stochastics.md b/docs/src/tutorials/01-adsorption-stochastics.md index e966e8e..f15d790 100644 --- a/docs/src/tutorials/01-adsorption-stochastics.md +++ b/docs/src/tutorials/01-adsorption-stochastics.md @@ -4,8 +4,6 @@ * Run simple RSA simulations: Aniline on Cu(111) * Basic evaluations -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup For the most simple RSA simulations two input files are needed: The coordinates of the adsorbate and the main input file of the RSA simulation. We will work with aniline as our adsorbate in this tutorial, so please save the following coordinates in an xyz file: diff --git a/docs/src/tutorials/02-benchmarks.md b/docs/src/tutorials/02-benchmarks.md index 8013400..7c1ab87 100644 --- a/docs/src/tutorials/02-benchmarks.md +++ b/docs/src/tutorials/02-benchmarks.md @@ -4,8 +4,6 @@ * Benchmark simulation cell size * Benchmark impact of rotation steps -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## General Every RSA simulation contains two important choices: The size of the unit cell as well as the number of rotations for every adsorbate. While the cell size can be adjusted based on a requested accuracy, the number of rotations should be motivated by the physics of the modeled system. Examples are small rotation steps for adsorbates that are considered to be freely rotating, a step size of 60° or 120° if an adsorbate is adapting to the symmetry of a Cu(111) surface, or even values of 180° or 360° (0°) if the adsorbate is assumend to be static. The value and number of valid rotations is therefore benchmarked to gain information on the sensitivity of the RSA simulations to this value. diff --git a/docs/src/tutorials/03-multiple-adsorbates.md b/docs/src/tutorials/03-multiple-adsorbates.md index 0acdda1..7fadae9 100644 --- a/docs/src/tutorials/03-multiple-adsorbates.md +++ b/docs/src/tutorials/03-multiple-adsorbates.md @@ -4,8 +4,6 @@ * Set up simulations with two or more adsorbates * Basic evalution of those simulations -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup Some simulations work with several adsorbates *simultanously*. In this case, every adsorbate must be provided by its own xyz file. In this tutorial we will use pyridine in its upright and tilted conformation as an example. Use the following coordinates to create two xyz files: diff --git a/docs/src/tutorials/04-multiple-grids.md b/docs/src/tutorials/04-multiple-grids.md index ad3b783..eb23836 100644 --- a/docs/src/tutorials/04-multiple-grids.md +++ b/docs/src/tutorials/04-multiple-grids.md @@ -4,8 +4,6 @@ * Set up simulations with two or more grids * Basic evalution of those simulations -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup The previous tutorial was based on working with multiple adsorbates. However, different adsorbates do not always prefer the same adsorption sites. Therefore, multiple grids are necessasry to offer different adsorption sites. In this tutorial we will work with methanesulfonic acid (MSA) and pyrrole as our adsorbates as these molecules prefer to adsorb at the hollow and on-top site, respectively. Create xyz files with the provided coordinates: diff --git a/docs/src/tutorials/05-events-rotations.md b/docs/src/tutorials/05-events-rotations.md index 35b53b6..d1c2f84 100644 --- a/docs/src/tutorials/05-events-rotations.md +++ b/docs/src/tutorials/05-events-rotations.md @@ -5,8 +5,6 @@ * Adjust input settings for "infinite" simulations * Evaluate rotation events -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup diff --git a/docs/src/tutorials/06-events-diffusions.md b/docs/src/tutorials/06-events-diffusions.md index 9e0c5aa..8bffc3c 100644 --- a/docs/src/tutorials/06-events-diffusions.md +++ b/docs/src/tutorials/06-events-diffusions.md @@ -5,8 +5,6 @@ * Adjust input settings for "infinite" simulations * Evaluate diffusion events -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup diff --git a/docs/src/tutorials/07-events-conformer-changes.md b/docs/src/tutorials/07-events-conformer-changes.md index 1ac9af5..e43249a 100644 --- a/docs/src/tutorials/07-events-conformer-changes.md +++ b/docs/src/tutorials/07-events-conformer-changes.md @@ -5,12 +5,10 @@ * Adjust input settings for "infinite" simulations * Evaluate conversion events -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup -For this tutorial you can use the coordinates of Pyridine from the [Molecule Library](@ref). The largest part of the main input file is identical to previous tutorials: +For this tutorial you can use the coordinates of pyridine from the [Molecule Library](@ref). The largest part of the main input file is identical to previous tutorials: ``` # Adsorption on Cu(111) Molecule diff --git a/docs/src/tutorials/08-events-conversions.md b/docs/src/tutorials/08-events-conversions.md index 20eaa22..2972288 100644 --- a/docs/src/tutorials/08-events-conversions.md +++ b/docs/src/tutorials/08-events-conversions.md @@ -3,8 +3,6 @@ !!! info "Learning Goals" * Combine conversion and diffusion events to mimic reactions -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup diff --git a/docs/src/tutorials/09-hdf5.md b/docs/src/tutorials/09-hdf5.md index ef5f20f..a1eb902 100644 --- a/docs/src/tutorials/09-hdf5.md +++ b/docs/src/tutorials/09-hdf5.md @@ -4,11 +4,9 @@ * Create HDF5 file to store all information * Read HDF5 for evaluation -!!! tip - Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. ## Input File Setup -While interactively working with RSA simulations is often a first step, productions runs are usually performed on high-performance computing centers and require the results to be stored. For this you must use the [HDF5](https://www.hdfgroup.org/solutions/hdf5/) features of this packaged. In this way you enable yourself to evaluate the RSA simulations at a later point and in addition are able to upload your data for any publication. Within this tutorial you can use the coordinates of Pyridine from the [Molecule Library](@ref). The main input file is identical to previous tutorials: +While interactively working with RSA simulations is often a first step, you might want the results to be stored. For this you must use the [HDF5](https://www.hdfgroup.org/solutions/hdf5/) features of this package. In this way you enable yourself to evaluate the RSA simulations at a later point and in addition are able to upload your data for any publication. Within this tutorial you can use the coordinates of pyridine from the [Molecule Library](@ref). The main input file is identical to previous tutorials: ``` # Adsorption on Cu(111) Molecule diff --git a/docs/src/tutorials/10-restarting.md b/docs/src/tutorials/10-restarting.md new file mode 100644 index 0000000..9de9a74 --- /dev/null +++ b/docs/src/tutorials/10-restarting.md @@ -0,0 +1,123 @@ +# [Tutorial 10: Restarting a Simulation Based on a Precovered Surface](@id tutorial-10) + +!!! info "Learning Goals" + * Use already created HDF5 file to restart RSA simulations + * Adsorb multiple molecules in sequence on a surface + + +## Input File Setup +All previous tutorials used a single adsorbate or multiple adsorbates simultaneously. To add multiple adsorbates in sequence a restart run is used. Basic steps are to create a HDF5 file in a first simulation and use a result from that calculation as the starting point for a new calculation. Consequently, at least two input files (for two adsorbates in sequence) are used. Within this tutorial you can use the coordinates of aniline and pyridine (upright structure) from the [Molecule Library](@ref). The first input file is nearly identical to previous tutorials: +``` +# Adsorption on Cu(111) +Molecule + rotationmodus = angle + rotationangle = 60.0 + fixpointtype = atoms + fixpointatoms = 1 + structure = ...ADJUST-YOUR-PATH.../aniline.xyz +End + +# Lattice of the Cu(111) surface +Lattice + transx = 30 + transy = 18 + + vectors + 2.51883 0.00000 0.00000 + 0.00000 4.36274 0.00000 + 0.00000 0.00000 1.00000 + end +End + +# On-top grid points of the Cu(111) surface +Grid + points + 0.00000 0.00000 0.00000 + 1.25942 2.18137 0.00000 + end +End + +# General settings for adsorption of aniline +Events + steps = 30 + + eventlist + 1 ads 1 1.0 + end +End +``` +The important change is that the number of steps per simulation is limited to 30. In this way we artificially stop the simulations before the surface is completely covered. Keep in mind that this trick is only meaningful for this tutorial. + + +The second input file contains in addition all information for pyridine. In addition three restart keywords are present, which state the path to the HDF5 file, the generation of RSA simulations used, and a list of the individual RSA simulations of this generation used as initial seed. +``` +# Adsorption on Cu(111) +Molecule + rotationmodus = angle + rotationangle = 60.0 + fixpointtype = atoms + fixpointatoms = 1 + structure = ...ADJUST-YOUR-PATH.../aniline.xyz +End + +Molecule + rotationmodus = angle + rotationangle = 60.0 + fixpointtype = atoms + fixpointatoms = 1 + structure = ...ADJUST-YOUR-PATH.../pyridine-upright.xyz +End + +# Lattice of the Cu(111) surface +Lattice + transx = 30 + transy = 18 + + vectors + 2.51883 0.00000 0.00000 + 0.00000 4.36274 0.00000 + 0.00000 0.00000 1.00000 + end +End + +# On-top grid points of the Cu(111) surface +Grid + points + 0.00000 0.00000 0.00000 + 1.25942 2.18137 0.00000 + end +End + +# General settings for adsorption of aniline & pyrrole +Events + steps = 1000 + + restart = 1 + restartruns = 1 115 541 + restartfile = ...ADJUST-YOUR-PATH.../input-1.h5 + + eventlist + 2 ads 1 1.0 + 1 dif 1 1 10.0 2.6 + 1 rot 1 10.0 + end +End +``` + +!!! warning + New molecules and grids of a restart run must appear after the original molecules and grids. Furthermore, you must not delete any molecule or grid block used in the initial calculations even if they are no longer used. + +## Running the Simulation +To start the simulations you still use the [`perform_multiple_rsa_runs`](@ref) function. You must use the optional hdf5 flag in both calls: +``` +NRuns = 1000 +inputfile_path = "...ADJUST-YOUR-PATH.../input-1.inp" +rsa_results-1, Nmolecules-1, molecules-1, Ngrids-1, grids-1, lattice-1, events-1 = perform_multiple_rsa_runs(NRuns, inputfile_path, hdf5 = true); + +inputfile_path = "...ADJUST-YOUR-PATH.../input-2.inp" +rsa_results-2, Nmolecules-2, molecules-2, Ngrids-2, grids-2, lattice-2, events-2 = perform_multiple_rsa_runs(NRuns, inputfile_path, hdf5 = true); +``` +The "h5" file will contain all information of both runs (as generation 1 and 2) while you can use all common analysis functions on the result structs. Keep in mind that the number of runs specified by `NRuns` will be performed for every selected run (1, 115, and 541) resulting in 3000 RSA simulations in this example. + +!!! info + The result structs of a restart run also include the information of the selected initial surface. For example, if you adsorb multiple adsorbates in a series of restart runs, every histogram counting the number of adsorbates will inlcude all adsorbates currently on the surface and not only the newly added ones. \ No newline at end of file diff --git a/docs/src/unused.md b/docs/src/unused.md new file mode 100644 index 0000000..fb23e39 --- /dev/null +++ b/docs/src/unused.md @@ -0,0 +1,11 @@ +## Using Multithreading with VSCode +Running RSA simulations over VSCode in parallel is possible by changing the "julia.NumThreads" setting. Simply search for "num thread" in the settings searchbar and change to your needs. +To test the new settings use the following command in your notebook: +``` +Threads.nthreads() +``` + + +# Was in every tutorial +!!! tip + Keep in mind that you can speed up simulations by using multiple threads as described in the [Using Multithreading with VSCode](@ref) section. \ No newline at end of file