readme.txt

Welcome to Pysic

Pysic is a calculator incorporating various empirical pair and many-body potentials in an object-based Python environment and user interface while implementing an efficient numeric core written in Fortran. The immediate aim of the Pysic project is to implement advanced variable charge potentials.

The code is developed as part of the EU FP7 Mordred project.

Pysic is open source, available at http://github.com/thynnine/pysic/ The official documentation is found at http://thynnine.github.com/pysic/

Contents of the Pysic repository

When you download Pysic, you should receive a package containing three directories [doc], [fortran], and [pysic]. The directory [doc] contains the source reStructuredText used for generating the documentation (with Sphinx). For readability, check the online version. The directories [fortran] and [pysic] contain the Fortran and Python source code, respectively. In addition to these folders, there should be a readme.txt file containing installation instructions and a Makefile for compiling with make.

Requirements

To compile and run Pysic you need:

• Python 2.x
• Numpy (which includes f2py)
• ASE

Pysic is designed to interface with the Atomic Simulation Environment package (ASE, developed by CAMd, DTU), and although in theory ASE is not a prerequisite for running Pysic, in practice you need it to do anything interesting.

Quick compilation

To compile Pysic, go to the directory where you have the Makefile and folders fortran and pysic, and enter the command make <target> on command line, where <target> is for instance serial or parallel. A list of available targets are shown with the command make help.

The default compilers listed in the Makefile are gfortran and mpif90. You may need to edit the names of the compilers to match those available on your system.

By default, make creates the pysic Python module as a folder named pysic (or pysic_debug etc., depending on the type of compilation) in the folder build. To run Pysic, copy the folder pysic to whereever you wish to run your simulations and import it in Python with import pysic.

Compilation under the hood

The Python part of Pysic does not have to be compiled separately, but the Fortran core must be. In order to link the Fortran and Python sides together, you need to compile the code with the f2py tool, which is part of the Numpy package.

The Fortran part is compiled with the commands::

f2py -m pysic_fortran -h pysic_fortran.pyf PyInterface.F90 f2py -c --fcompiler=gfortran --f90exec=mpif90 --f90flags="-D MPI"
pysic_fortran.pyf Mersenne.F90 MPI.F90 Quaternions.F90 Utility.F90
Geometry.F90 Potentials.F90 Core.F90 PyInterface.F90

The first run creates the interface file pysic_fortran.pyf from the Fortran source file PyInterface.F90. The second run compiles the rest of the code in a native Fortran mode and creates the Python accessible binary file pysic_fortran.so. From this file, the subroutines of PyInterface.F90 are callable as Python functions.

The created pysic_fortran.so appears in Python as a module pysic_fortran.pysic_interface. The package structure of pysic expects to find it at pysic.pysic_fortran.pysic_interface, i.e., the .so file should be in the folder pysic (the root folder of the Python package). The Makefile should take care of putting it in the right place, but if you decide to compile the Fortran part manually, keep in mind that the file needs to be moved there.