{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Tutorial: Simlammps wrapper\n", "In this tutorial we will go through a simple example of how to use the wrapper for the LAMMPS simulation engine.\n", "You can find the wrapper [here](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/simlammps).\n", "\n", "## Background\n", "A wrapper for LAMMPS has been present in SimPhoNy since its initial version, and it is the first simulation engine we supported in version 3.\n", "\n", "This wrapper is a good example of the [3-layered-design](../detailed_design.md) where the Syntactic layer is a third party library.\n", "In this case we use PyLammps, a Python binding for LAMMPS created and maintained by the LAMMPS developers." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Let's get hands on\n", "### Installation\n", "We will start by quickly going through the installation of this tool.\n", "Like we explain in the [wrapper development section](../wrapper_development.md#engine-installation), there are two options:\n", "\n", "- Using Docker: run `./docker_install.sh`.\n", "- Local installation: remember that you must have a compatible version of [OSP-core installed](../installation.md).\n", " \n", " Install the ontology via `pico install simlammps.ontology.yml.`\n", " \n", " Run `./install_engine.sh`.\n", "\n", " - Note that you will be asked for a superuser password to install required libraries for the installation (make, libjpeg, libpng...)\n", "\n", " - Currently we support Ubuntu and centOS.\n", " \n", " Install the wrapper by running `python setup.py install`.\n", "\n", "That should be all needed to use simlammps!\n", "\n", "### Simple example\n", "This is an adaptation of simlammps/examples/small.py.\n", "As usual, we start importing the necessary components:" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "from osp.core import simlammps_ontology\n", "from osp.wrappers.simlammps import SimlammpsSession" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We create the wrapper instance.\n", "All wrappers are created by defining their own [session class](../detailed_design.md#session).\n", "\n", "There is no need to specify a syntactic layer (PyLammps). The session will generate one." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "LAMMPS output is captured by PyLammps wrapper\n" ] } ], "source": [ "simlammps_session = SimlammpsSession()\n", "simlammps = simlammps_ontology.SimlammpsWrapper(session=simlammps_session)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Next, we can define some necessary settings for the run:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Define the simulation box\n", "box = simlammps_ontology.SimulationBox()\n", "face_x = simlammps_ontology.FaceX(vector=(10, 0, 0))\n", "face_x.add(simlammps_ontology.Periodic())\n", "face_y = simlammps_ontology.FaceY(vector=(0, 10, 0))\n", "face_y.add(simlammps_ontology.Periodic())\n", "face_z = simlammps_ontology.FaceZ(vector=(0, 0, 10))\n", "face_z.add(simlammps_ontology.Periodic())\n", "box.add(face_x, face_y, face_z)\n", "simlammps.add(box)\n", "\n", "# molecular dynamics model\n", "md_nve = simlammps_ontology.MolecularDynamics()\n", "simlammps.add(md_nve)\n", "\n", "# solver component:\n", "sp = simlammps_ontology.SolverParameter()\n", "\n", "# integration time:\n", "steps = 100\n", "itime = simlammps_ontology.IntegrationTime(steps=steps)\n", "\n", "sp.add(itime)\n", "verlet = simlammps_ontology.Verlet()\n", "\n", "sp.add(verlet)\n", "simlammps.add(sp)\n", "\n", "# Mass and material for the atoms\n", "mass = simlammps_ontology.Mass(value=0.2)\n", "material = simlammps_ontology.Material()\n", "\n", "material.add(mass)\n", "simlammps.add(material)\n", "\n", "# Interatomic force as material relation\n", "lj = simlammps_ontology.LennardJones_6_12(cutoff_distance=2.5,\n", " energy_well_depth=1.0,\n", " van_der_waals_radius=1.0)\n", "lj.add(material)\n", "simlammps.add(lj)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we add some atoms:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "particle = simlammps_ontology.Atom()\n", "particle.add(material, \n", " simlammps_ontology.Position(vector=(1, 6, 3)),\n", " simlammps_ontology.Velocity(vector=(1, 0, 0)))\n", "simlammps.add(particle)\n", "\n", "particle = simlammps_ontology.Atom()\n", "particle.add(material,\n", " simlammps_ontology.Position(vector=(2, 1, 4)),\n", " simlammps_ontology.Velocity(vector=(2, 0, 2)))\n", "simlammps.add(particle)\n", "\n", "particle = simlammps_ontology.Atom()\n", "# The velocity is not required (the position is)\n", "particle.add(material,\n", " simlammps_ontology.Position(vector=(7, 3, 0)))\n", "simlammps.add(particle)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To run the simulation, we call the `run()` method of the session.\n", "The run method sends the information to the engine, and tells it to run the number of steps defined in the Integration Time entity (100):" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "simlammps.session.run()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Since we will run the simulation a couple of times, we can define a simple function for showing the position and velocities of the atoms:" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "def print_info():\n", " for atom in simlammps.iter(oclass=simlammps_ontology.Atom):\n", " # Remember that Cuds.get(oclass) returns a list\n", " # We now all atoms have one (and only one) position\n", " position = atom.get(oclass=simlammps_ontology.Position)[0]\n", " # But the atoms might not have a velocity\n", " velocity = atom.get(oclass=simlammps_ontology.Velocity)\n", " print(\"Atom \" + str(atom.uid) + \":\")\n", " print(\" - Position: \" + str(position.vector))\n", " if velocity:\n", " print(\" - Velocity: \" + str(velocity[0].vector))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can easily print the results of the run:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Atom fd4199d4-4d1a-425c-8010-60efca65bd1c:\n", " - Position: [1.5 6. 3. ]\n", " - Velocity: [1. 0. 0.]\n", "Atom f9a32d14-b638-4796-9407-4b1ae6be43cb:\n", " - Position: [3. 1. 5.]\n", " - Velocity: [2. 0. 2.]\n", "Atom db96a76f-4d70-4e19-b460-46ee286f831e:\n", " - Position: [7. 3. 0.]\n" ] } ], "source": [ "print_info()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally, let's change the velocities and run again, but now for 200 steps:" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Atom fd4199d4-4d1a-425c-8010-60efca65bd1c:\n", " - Position: [0.5 4. 6. ]\n", " - Velocity: [-1. -2. 3.]\n", "Atom f9a32d14-b638-4796-9407-4b1ae6be43cb:\n", " - Position: [6. 8. 8.]\n", " - Velocity: [ 3. -3. 3.]\n", "Atom db96a76f-4d70-4e19-b460-46ee286f831e:\n", " - Position: [9. 4. 0.]\n", " - Velocity: [2. 1. 0.]\n" ] } ], "source": [ "from random import randint\n", "\n", "for atom in simlammps.iter(oclass=simlammps_ontology.Atom):\n", " # But the atoms might not have a velocity\n", " velocity = atom.get(oclass=simlammps_ontology.Velocity)\n", " if velocity:\n", " velocity[0].vector = (randint(-3, 3), randint(-3, 3), randint(-3, 3))\n", " else:\n", " atom.add(simlammps_ontology.Velocity(vector = (randint(-3, 3), randint(-3, 3), randint(-3, 3))))\n", "\n", "solver_parameter = simlammps.get(oclass=simlammps_ontology.SolverParameter)[0]\n", "integration_time = solver_parameter.get(oclass=simlammps_ontology.IntegrationTime)[0]\n", "integration_time.steps = 200\n", "\n", "simlammps.session.run()\n", "print_info()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 2 }