LAMMPS Analyser

A language server and command line tool for LAMMPS Input Scripts

LAMMPS analyser checks your input scripts for errors whilst writing them and without having to run the simulation.

Installation

Pre-built binaries

An install script provides pre-built binaries on macOS and Linux:

    curl --proto '=https' --tlsv1.2 -LsSf https://github.com/chappertron/lammps-analyser/releases/download/0.1.0-pre-release-3/lammps-analyser-installer.sh | sh

or for Windows

    powershell -ExecutionPolicy ByPass -c "irm https://github.com/chappertron/lammps-analyser/releases/download/0.1.0-pre-release-3/lammps-analyser-installer.ps1 | iex"

This script is generated by cargo-dist

Installing via Cargo

If you have the rust toolchain installed, consider installing via Cargo with:

cargo install --locked lammps-analyser

You can also clone this repo and build directly from source, of course.

Using From the Command Line

lammps-analyser in.input_script

This outputs a nice list of errors

Using with a text editor

LAMMPS analyser is just the server side of the Language Server (LS) Protocol. To use with a text editor you need to have a client for it.

Neovim and other text editors have a built-in client for supporting any LS. VS Code requires a different client for every language server.

Lammps-analyser does not yet provide syntax highlighting through the language server. In VS Code use the lammps_vscode extension to provide highlighting In Neovim and other editors use tree-sitter along with the treesitter-lammps grammar. If you're not sure where to get started, Google your editor + tree-sitter.

Navigate to the section appropriate for your editor.

VS Code

There isn't currently a dedicated client for lammps-analyser. Instead, you need to install a generic LSP client, such as glspc. Ideally glspc won't be required and a custom LSP client will be available.

It is recommended you also install the lammps-vscode plugin if you want syntax highlighting and file type detection.

Steps

1. Install lammps-analyser, following the guide above
2. Install glspc and lammps-vscode plugins in VS Code.
3. Configure glspc to start the lmp-lsp executable for the file type 'lmps' (provided by vscode_lammps). This is done by going to Settings > Extensions > Generic LSP Client. Then set Glspc: Language ID to lmps and Glspc: Server Path to lmp-lsp (or wherever you installed it if not in your path).
4. Reload VS Code and open a LAMMPS script to check your work. By default, lammps_vscode detects the following patterns in file names as LAMMPS input scripts: ".lmp", ".lmps" and ".lammps" and "in."

Neovim

1. Install lammps-analyser as above

2. If you don't already have a Neovim configuration, create one using kickstart.nvim or use a pre-configured version of Neovim.

3. Set up a LAMMPS file type somewhere in your config (such as in init.lua)

    -- LAMMPS File type
    vim.filetype.add {
      extension = {
        lmp = 'lammps',
      },
   
      pattern = {
        -- These are lua matching patterns, not regex
        ['.*%.lmp'] = 'lammps',
        ['in%..*'] = 'lammps',
        ['.*%.in'] = 'lammps',
      },
    }
   

   Feel free to change the lua-patterns to match the extensions and prefixes you use for input scripts.

4. Set up the LSP server using the nvim-lspconfig plugin. In my case I used the following snippet:

    -- More LSP Config; Getting LAMMPS LSP Working
    -- Defining the LSP set up (using lsp-config), but not in it's own module.
    -- local lspconfig = require "lspconfig"
    local util = require 'lspconfig/util'
    local configs = require 'lspconfig.configs'
   
    local lmp_default_config = {
      cmd = { 'lmp-lsp' }, -- Make sure you change this to where this is located
      filetypes = { 'lammps' },
      root_dir = util.find_git_ancestor,
      single_file_support = true,
    }
   
    configs.lmp_lsp = {
      default_config = lmp_default_config,
      docs = {
        description = [[
          "LAMMPS LSP server"
          ]],
        default_config = {
          root_dir = [[util.find_git_ancestor]],
        },
      },
    }
   
    -- LSP
    require('lspconfig').lmp_lsp.setup {}
   
   

5. For syntax highlighting follow the guide in the tree-sitter-lammps repo README.

Others Editors

For other editors look into whether it natively supports the Language Server Protocol or if there is a plugin for it. The same for tree-sitter syntax highlighting.

For example, Emacs has an LSP plugin and also options for tree-sitter, including being built in to newer versions.

There should also be plugins for these with regular Vim

Limitations and Reporting Issues

This project does not aim to and cannot catch every possible error in a simulation script. It instead aims to reduce the number of errors encountered at runtime.

If have a valid input script that lammps-analyser reports as erroneous, please raise an issue.

If you have an invalid script that doesn't show any errors, you are also welcome to report an issue. Do note, these will be treated as feature requests and will have a lower priority than false negatives.

There are several syntax features that are not yet handled, most notably single quoted strings and triple quotes. Soon there will be an issue tracking for features such as these, either here or in tree-sitter-lammps.

Minimum Supported Version of Rust

Building requires Rust > 1.65

Licence

This project uses the GPL-2.0 Licence to be compatible with that of LAMMPS.

The lammps_docs_md folder contains documentation generated from the official LAMMPS documentation.