Atomsk

The Swiss-army knife of atomic simulations

Contribute

Atomsk can still be improved in many ways. If you wish to help, then you may edit the source code to fix a bug, optimize a routine, add a new feature, and modify or add translations of the messages. You may also translate the documentation of Atomsk, so that users read it in their native language. Your contribution is welcome!

Report a bug

If you found a bug when running Atomsk, you may open an issue on GitHub, or contact the author by email.

A bug can be any behaviour that is not desired: a result that is incorrect or inconsistent, a bad translation, a crash or a segmentation fault. When submitting a bug report, please indicate the version of Atomsk you are using, and the command that produces the bug. Also if possible, explain what result you expected when running that command, and why you think Atomsk's behaviour is wrong.

Use Git and Github

Atomsk is developped using Git, and its development is made public on the platform GitHub. To learn how to use Git (the version management software itself), and how to use Github (the platform hosting Atomsk), the following links provide a good start:

Also, do not hesitate to ask your favorite search engine for more information and tutorials.

Get the development version of Atomsk

If you just wish to download the latest development version of Atomsk, then create a directory on your computer and type the following command:

git clone https://github.com/pierrehirel/atomsk

Beware, however, that this version may contain features that are not completely implemented, bugs, or may even not compile or not work at all. Use it at your own risks.

How to contribute to Atomsk

If you wish to contribute to Atomsk, follow these steps:

  1. Create your own account on GitHub.com. Please use your actual name (not a pseudonym).
  2. Go to the GitHub page of Atomsk and click the "Fork" button; this will create a copy of Atomsk on your own GitHub account.
  3. Clone this copy to your local computer (make sure you have Git installed and configured on your computer):

    git clone https://github.com/my_name/my_repository

  4. Now, instead of working directly on the master branch (which can create conflicts), it is safer to create a separate branch:

    git checkout -b my_branch

  5. Work on your own copy of Atomsk, modify the files to your liking. Compile your version to test if your modifications work. Don't forget to insert comments in your source code.
  6. Once your work is done, commit your modifications (with comments!):

    git commit -a


    Then, push them to your GitHub repository:

    git push origin my_branch


    Git will ask for your GitHub user name and password.
  7. Open your Web browser, go to the GitHub page of your repository, and click the "Pull request" button.

Your modifications will appear to the main author as a "Pull request". After reviewing your modifications, they may be accepted and merged with the main Atomsk (or not).

Send your modified version by email

Alternatively, if you cannot or don't want to use GitHub, you can send your modified version of Atomsk directly by email. In this case, please archive your whole modified copy (in zip or tar.gz format) before sending it. If possible or relevant, you may also send some example scripts to illustrate the changes you have made.

Important guidelines and good practices

Contributions are welcome. Contributions are good. However to avoid chaos, it is recommended to comply to the following guidelines when you contribute to Atomsk.