Getting started
===============

Git version control
-------------------

MetalWalls is developped using [Git][Git], an open source version control system. 
The main development version of MW is hosted on a [gitlab server at Maison de la Simulation][gitlab mw2] and is a private repository. To gain access to this repository, see [below](#setup-account). 
The development branch is the **master** branch whereas the stable release branch is **release**. Versions are indicated using *tags*. These can be visualized on the gitlab webpage in *Repository>Tags*
or with the command
```bash
git tag
# and
git show <tag-name>
```

To add new features to MW, these are coded in separate branches that are then merged in the **master**. 
There is also a second public remote that hosts the repository on [Gitlab][gitlab] where the **release** branch is published along with the *tags*.

All developments are made on the private repository, which also has a [CI](continuous-integration) to check each new commit. In addition, release versions of the code are published on the public repository.
After cloning the development git repository, these are the steps to push onto the second (public) remote: 
```bash
git remote add public git@gitlab.com:ampere2/metalwalls.git      # to do just once
git push public release --tags
```
This is only possible for users with maintainer access.

To handle both remotes smoothly, **no modification should be done directly on the public remote**. Although it is not recommended, 
users without access to the private repository can submit merge requests on the public repository that will be considered.
 

The wiki is also a git repository. It only has a **master** branch and the steps to push onto the public remote are:
```bash
git remote add public git@gitlab.com:ampere2/metalwalls.wiki.git    # to do just once
git push public master
```


<a name="setup-account">

Setup a user account
--------------------

</a>

To set up a GitLab account at Maison de la Simulation, please contact Professor Mathieu Salanne at
mathieu.salanne@sorbonne-universite.fr 

Once the account is open, you can set up an ssh authentification. For this, go to
the *User Settings > SSH Keys* configuration page from your profile settings.


Download the source code
------------------------

To download the source code with the earliest developpements

```bash
git clone git@gitlab.maisondelasimulation.fr:amarinla/mw2.git
```

If for any reason, you are not able to setup ssh authentification, you
can try to download the source code using https protocol. You will be
prompted for your username and password:

```bash
git clone https://gitlab.maisondelasimulation.fr/amarinla/mw2.git
```

Directories
-----------

- *./src* contains all the fortran source files and python scripts
- *./doc* contains some documentation
- *./tests* contains regression tests used in the [continuous integration](continuous-integration)
- *./computers* contains machine specific files
- *./scripts* contains utility/helper scripts
- *./example* contains examples
- *./tools* contains analysis scripts

To build and run tests, see the [installation instructions](install).



Coding style
------------

- The code is written in modern style Fortran 90.
- There should be only modules and program source files.
- Fortran files end with the extension '.f90', except if they contain preprocessor directives in which case the extension is '.F90'
- Indent 3 spaces for each block structure.
- Use lowercase for Fortran keywords.
- Use explicit variable names, using underscore ('_') to separate words.
- Use uppercase for variables with the 'parameter' attribute.
- Use save attribute for module variables which are not parameters
- Don't forget to comment what you are coding.
- module names must be prepended with MW_
- subroutines defined inside a submodule should have a clear and concise name

- if a module defines a type then it should also define the following subroutines:
    * define_type : allocate arrays and initialize values in the data type
    * void_type : deallocate arrays and reset values in the data type
    * print_type : print content of the data type to a unit

- when using routines from a different module use the only and renaming feature
  of the *use* statement. When renaming prepend the module name to the
  subroutine name.

  Example subroutine sub2 in module MW_foo is calling subroutine sub1 from
  module MW_bar:
```fortran
  module MW_bar
  implicit none
  contains
     subroutine sub1()
        implicit none
        ...
     end subroutine sub1
  end module MW_bar

  module MW_foo
  implicit none
  contains
     subroutine sub2()
        use MW_bar, only: MW_bar_sub1 => sub1
        implicit none
        ...
        call MW_bar_sub1()
        ...
     end subroutine sub2
  end module MW_foo
```

- for historic reasons, the word `ion` designates an electrolyte atom and the word `atom` designates an electrode atom (for example, the array containing the electrolyte atoms coordinates is called `xyz_ions`, and the one containing the electrode atoms coordinates is `xyz_atoms`). Moreover, the `intermolecular` word is used for the van der Waals part of the intermolecular part of the interactions, excluding the Coulomb part.


[gitlab mw2]: https://gitlab.maisondelasimulation.fr/amarinla/mw2
[Git]: https://git-scm.com/
[gitlab]: https://gitlab.com/ampere2/metalwalls
