# 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.

<!-- TODO: Commandline output image -->
<!-- TODO: Screenshot of in editor highlighting and errors -->

## Installation

### Pre-built binaries

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

``` bash
    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
    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](https://github.com/axodotdev/cargo-dist)

### Installing via Cargo

If you have the [rust toolchain]() installed, consider installing via Cargo with:

``` sh
cargo install --locked lammps-analyser
```

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

## Using From the Command Line

``` bash
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](https://marketplace.visualstudio.com/items?itemName=ThFriedrich.lammps) 
extension to provide highlighting
In Neovim and other editors use [tree-sitter](https://github.com/tree-sitter/tree-sitter)
along with the [treesitter-lammps](https://github.com/chappertron/tree-sitter-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](https://marketplace.visualstudio.com/items?itemName=torokati44.glspc).
Ideally glspc won't be required and a custom LSP client will be available.

It is recommended you also install the [lammps-vscode](https://marketplace.visualstudio.com/items?itemName=ThFriedrich.lammps) 
plugin if you want syntax highlighting and file type detection.

#### Steps

1. Install lammps-analyser, following the guide above
2. Install [glspc](https://marketplace.visualstudio.com/items?itemName=torokati44.glspc)
    and [lammps-vscode](https://marketplace.visualstudio.com/items?itemName=ThFriedrich.lammps) 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](https://github.com/nvim-lua/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`)

   ```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](https://www.lua.org/pil/20.2.html) to match the extensions and prefixes you use for input scripts.

4. Set up the LSP server using the [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) plugin.
   In my case I used the following snippet:

   ```lua
    -- 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](https://github.com/chappertron/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](https://github.com/emacs-lsp/lsp-mode) 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](https://github.com/chappertron/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](https://docs.lammps.org/Manual.html).