{ "metadata": { "name": "" }, "nbformat": 3, "nbformat_minor": 0, "worksheets": [ { "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Fortran magic's documentation\n", "\n", "Fortran magic is an [IPython](http://ipython.org) extension that help to use fortran code in an interactive session. \n", "\n", "It adds a `%%fortran` cell magic that compile and import the Fortran code in the cell, using [F2py](http://wiki.scipy.org/F2py).\n", "\n", "The contents of the cell are written to a `.f90` file in the\n", "directory `IPYTHONDIR/fortran` using a filename with the hash of the\n", "code. This file is then compiled. The resulting module\n", "is imported and all of its symbols are injected into the user's\n", "namespace.\n", "\n", "\n", "* Author: Mart\u00edn Gait\u00e1n \n", "* Homepage: https://github.com/mgaitan/fortran_magic \n", "* License: BSD\n", "\n", "This software was sponsored by [Phasety](http://phasety.com)\n", "\n", "Feedback, report of issues and pull requests are welcome!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Install\n", "\n", "You can install or upgrade via `pip`\n", "\n", " pip install -U fortran-magic\n", "\n", "or directly from the repository using `%install_ext` magic command. This is needed just the first time. " ] }, { "cell_type": "code", "collapsed": false, "input": [ "%install_ext https://raw.github.com/mgaitan/fortran_magic/master/fortranmagic.py" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "Installed fortranmagic.py. To use it, type:\n", " %load_ext fortranmagic\n" ] } ], "prompt_number": 1 }, { "cell_type": "markdown", "metadata": {}, "source": [ "Then you are ready to load the magic " ] }, { "cell_type": "code", "collapsed": false, "input": [ "%load_ext fortranmagic" ], "language": "python", "metadata": {}, "outputs": [ { "javascript": [ "$.getScript(\"https://raw.github.com/marijnh/CodeMirror/master/mode/fortran/fortran.js\", function () {\n", "IPython.config.cell_magic_highlight['magic_fortran'] = {'reg':[/^%%fortran/]};});\n" ], "metadata": {}, "output_type": "display_data" } ], "prompt_number": 2 }, { "cell_type": "markdown", "metadata": {}, "source": [ "To load it each time IPython starts, list it in your configuration file:\n", "\n", " c.InteractiveShellApp.extensions = [\n", " 'fortranmagic'\n", " ]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic example\n", "\n", "Just mark the cell with `%%fortran` in the first line. The code will be highlighted accordingly and compiled when the cell is run " ] }, { "cell_type": "code", "collapsed": false, "input": [ "%%fortran\n", "\n", "subroutine f1(x, y, z)\n", " real, intent(in) :: x,y\n", " real, intent(out) :: z\n", "\n", " z = sin(x+y)\n", "\n", "end subroutine f1" ], "language": "python", "metadata": {}, "outputs": [], "prompt_number": 3 }, { "cell_type": "code", "collapsed": false, "input": [ "f1(1.0, 2.1415)" ], "language": "python", "metadata": {}, "outputs": [ { "metadata": {}, "output_type": "pyout", "prompt_number": 4, "text": [ "9.26574066397734e-05" ] } ], "prompt_number": 4 }, { "cell_type": "code", "collapsed": false, "input": [ "print f1.__doc__" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "f1 - Function signature:\n", " z = f1(x,y)\n", "Required arguments:\n", " x : input float\n", " y : input float\n", "Return objects:\n", " z : float\n", "\n" ] } ], "prompt_number": 5 }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Verbosity\n", "\n", "By default the magic only returns output when the compilation process fails. But you can increase the verbosity with the flag `-v`" ] }, { "cell_type": "code", "collapsed": false, "input": [ "%%fortran -v \n", "\n", "module hi\n", " integer :: five = 5\n", "end module " ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "\n", "Ok. The following fortran objects are ready to use: hi\n" ] } ], "prompt_number": 6 }, { "cell_type": "code", "collapsed": false, "input": [ "%%fortran -vv \n", "\n", "module hi\n", " integer :: five = 5\n", "end module " ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "Running...\n", " f2py -m _fortran_magic_c3329f973fb44fd5c93af2960628c6b6 -c /home/tin/.cache/ipython/fortran/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6.f90\n", "\n", "Ok. The following fortran objects are ready to use: hi" ] }, { "output_type": "stream", "stream": "stdout", "text": [ "\n" ] } ], "prompt_number": 7 }, { "cell_type": "code", "collapsed": false, "input": [ "%%fortran -vvv\n", "\n", "module hi\n", " integer :: five = 5\n", "end module " ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "Running...\n", " f2py -m _fortran_magic_c3329f973fb44fd5c93af2960628c6b6 -c /home/tin/.cache/ipython/fortran/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6.f90\n", "running build\n", "running config_cc\n", "unifing config_cc, config, build_clib, build_ext, build commands --compiler options\n", "running config_fc\n", "unifing config_fc, config, build_clib, build_ext, build commands --fcompiler options\n", "running build_src\n", "build_src\n", "building extension \"_fortran_magic_c3329f973fb44fd5c93af2960628c6b6\" sources\n", "f2py options: []\n", "f2py:> /tmp/tmpoh2WVC/src.linux-x86_64-2.7/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6module.c\n", "creating /tmp/tmpoh2WVC\n", "creating /tmp/tmpoh2WVC/src.linux-x86_64-2.7\n", "Reading fortran codes...\n", "\tReading file '/home/tin/.cache/ipython/fortran/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6.f90' (format:free)\n", "Post-processing...\n", "\tBlock: _fortran_magic_c3329f973fb44fd5c93af2960628c6b6\n", "\t\t\tBlock: hi\n", "Post-processing (stage 2)...\n", "\tBlock: _fortran_magic_c3329f973fb44fd5c93af2960628c6b6\n", "\t\tBlock: unknown_interface\n", "\t\t\tBlock: hi\n", "Building modules...\n", "\tBuilding module \"_fortran_magic_c3329f973fb44fd5c93af2960628c6b6\"...\n", "\t\tConstructing F90 module support for \"hi\"...\n", "\t\t Variables: five\n", "\tWrote C/API module \"_fortran_magic_c3329f973fb44fd5c93af2960628c6b6\" to file \"/tmp/tmpoh2WVC/src.linux-x86_64-2.7/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6module.c\"\n", "\tFortran 90 wrappers are saved to \"/tmp/tmpoh2WVC/src.linux-x86_64-2.7/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6-f2pywrappers2.f90\"\n", " adding '/tmp/tmpoh2WVC/src.linux-x86_64-2.7/fortranobject.c' to sources.\n", " adding '/tmp/tmpoh2WVC/src.linux-x86_64-2.7' to include_dirs.\n", "copying /usr/lib/python2.7/dist-packages/numpy/f2py/src/fortranobject.c -> /tmp/tmpoh2WVC/src.linux-x86_64-2.7\n", "copying /usr/lib/python2.7/dist-packages/numpy/f2py/src/fortranobject.h -> /tmp/tmpoh2WVC/src.linux-x86_64-2.7\n", " adding '/tmp/tmpoh2WVC/src.linux-x86_64-2.7/_fortran_magic_c3329f973fb44fd5c93af2960628c6b6-f2pywrappers2.f90' to sources.\n", "build_src: building npy-pkg config files\n", "running build_ext\n", "customize UnixCCompiler\n", "customize UnixCCompiler using build_ext\n", "customize GnuFCompiler\n", "customize IntelFCompiler\n", "customize LaheyFCompiler\n", "customize PGroupFCompiler\n", "customize AbsoftFCompiler\n", "customize NAGFCompiler\n", "customize VastFCompiler\n", "customize CompaqFCompiler\n", "customize IntelItaniumFCompiler\n", "customize IntelEM64TFCompiler\n", "customize Gnu95FCompiler\n", "customize Gnu95FCompiler\n", "customize Gnu95FCompiler using build_ext\n", "running scons\n", "Removing build directory /tmp/tmpoh2WVC\n" ] }, { "output_type": "stream", "stream": "stdout", "text": [ "\n", "Ok. The following fortran objects are ready to use: hi\n" ] } ], "prompt_number": 8 }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Using f2py options\n", "\n", "Almost all f2py's command line options are exposed to the `%%fortran` cell magic. See the docstring for detail. For example:" ] }, { "cell_type": "code", "collapsed": false, "input": [ "%%fortran --fcompiler gnu95 --compiler unix --f90flags \"-d\" --noarch\n", "C\n", " SUBROUTINE ZADD(A,B,C,N)\n", "C\n", " DOUBLE COMPLEX A(*)\n", " DOUBLE COMPLEX B(*)\n", " DOUBLE COMPLEX C(*)\n", " INTEGER N\n", " DO 20 J = 1, N\n", " C(J) = A(J)+B(J)\n", " 20 CONTINUE\n", " END\n" ], "language": "python", "metadata": {}, "outputs": [], "prompt_number": 9 }, { "cell_type": "code", "collapsed": false, "input": [ "print(zadd.__doc__)" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "zadd - Function signature:\n", " zadd(a,b,c,n)\n", "Required arguments:\n", " a : input rank-1 array('D') with bounds (*)\n", " b : input rank-1 array('D') with bounds (*)\n", " c : input rank-1 array('D') with bounds (*)\n", " n : input int\n", "\n" ] } ], "prompt_number": 10 }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Linking resources\n", "\n", "Use `--link` option. This is `--link-` in f2py command line" ] }, { "cell_type": "code", "collapsed": false, "input": [ "%%fortran --link lapack -vv\n", "\n", "subroutine solve(A, b, x, n)\n", " ! solve the matrix equation A*x=b using LAPACK\n", " implicit none\n", "\n", " real*8, dimension(n,n), intent(in) :: A\n", " real*8, dimension(n), intent(in) :: b\n", " real*8, dimension(n), intent(out) :: x\n", "\n", " integer :: i, j, pivot(n), ok\n", "\n", " integer, intent(in) :: n\n", " x = b\n", "\n", " ! find the solution using the LAPACK routine SGESV\n", " call DGESV(n, 1, A, n, pivot, x, n, ok)\n", " \n", "end subroutine" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "Running...\n", " f2py --link-lapack -m _fortran_magic_0bca4954c47bf4491cf9b8e8f3ab6888 -c /home/tin/.cache/ipython/fortran/_fortran_magic_0bca4954c47bf4491cf9b8e8f3ab6888.f90\n", "\n", "Ok. The following fortran objects are ready to use: solve" ] }, { "output_type": "stream", "stream": "stdout", "text": [ "\n" ] } ], "prompt_number": 11 }, { "cell_type": "code", "collapsed": false, "input": [ "import numpy as np\n", "A = np.array([[1, 2.5], [-3, 4]])\n", "b = np.array([1, 2.5])" ], "language": "python", "metadata": {}, "outputs": [], "prompt_number": 12 }, { "cell_type": "code", "collapsed": false, "input": [ "solve(A, b)" ], "language": "python", "metadata": {}, "outputs": [ { "metadata": {}, "output_type": "pyout", "prompt_number": 13, "text": [ "array([-0.19565217, 0.47826087])" ] } ], "prompt_number": 13 }, { "cell_type": "markdown", "metadata": {}, "source": [ "Which is, by the way, the same than" ] }, { "cell_type": "code", "collapsed": false, "input": [ "np.linalg.solve(A, b)" ], "language": "python", "metadata": {}, "outputs": [ { "metadata": {}, "output_type": "pyout", "prompt_number": 14, "text": [ "array([-0.19565217, 0.47826087])" ] } ], "prompt_number": 14 }, { "cell_type": "markdown", "metadata": {}, "source": [ "## f2py help\n", "\n", "F2py has some flag that output help. See the docstring of `%f2py_help`" ] }, { "cell_type": "code", "collapsed": false, "input": [ "%f2py_help --link blas" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "blas_info:\n", " libraries blas not found in /usr/local/lib\n", " libraries blas not found in /usr/lib64\n", " FOUND:\n", " libraries = ['blas']\n", " library_dirs = ['/usr/lib']\n", " language = f77\n", "\n" ] } ], "prompt_number": 15 }, { "cell_type": "code", "collapsed": false, "input": [ "%f2py_help --fcompiler" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "Gnu95FCompiler instance properties:\n", " archiver = ['/usr/bin/gfortran', '-cr']\n", " compile_switch = '-c'\n", " compiler_f77 = ['/usr/bin/gfortran', '-Wall', '-ffixed-form', '-fno-\n", " second-underscore', '-fPIC', '-O3', '-funroll-loops']\n", " compiler_f90 = ['/usr/bin/gfortran', '-Wall', '-fno-second-underscore',\n", " '-fPIC', '-O3', '-funroll-loops']\n", " compiler_fix = ['/usr/bin/gfortran', '-Wall', '-ffixed-form', '-fno-\n", " second-underscore', '-Wall', '-fno-second-underscore', '-\n", " fPIC', '-O3', '-funroll-loops']\n", " libraries = ['gfortran']\n", " library_dirs = []\n", " linker_exe = ['/usr/bin/gfortran', '-Wall', '-Wall']\n", " linker_so = ['/usr/bin/gfortran', '-Wall', '-Wall', '-shared']\n", " object_switch = '-o '\n", " ranlib = ['/usr/bin/gfortran']\n", " version = LooseVersion ('4.7.2-2')\n", " version_cmd = ['/usr/bin/gfortran', '--version']\n", "Fortran compilers found:\n", " --fcompiler=gnu95 GNU Fortran 95 compiler (4.7.2-2)\n", "Compilers available for this platform, but not found:\n", " --fcompiler=absoft Absoft Corp Fortran Compiler\n", " --fcompiler=compaq Compaq Fortran Compiler\n", " --fcompiler=g95 G95 Fortran Compiler\n", " --fcompiler=gnu GNU Fortran 77 compiler\n", " --fcompiler=intel Intel Fortran Compiler for 32-bit apps\n", " --fcompiler=intele Intel Fortran Compiler for Itanium apps\n", " --fcompiler=intelem Intel Fortran Compiler for 64-bit apps\n", " --fcompiler=lahey Lahey/Fujitsu Fortran 95 Compiler\n", " --fcompiler=nag NAGWare Fortran 95 Compiler\n", " --fcompiler=pathf95 PathScale Fortran Compiler\n", " --fcompiler=pg Portland Group Fortran Compiler\n", " --fcompiler=vast Pacific-Sierra Research Fortran 90 Compiler\n", "Compilers not available on this platform:\n", " --fcompiler=hpux HP Fortran 90 Compiler\n", " --fcompiler=ibm IBM XL Fortran Compiler\n", " --fcompiler=intelev Intel Visual Fortran Compiler for Itanium apps\n", " --fcompiler=intelv Intel Visual Fortran Compiler for 32-bit apps\n", " --fcompiler=intelvem Intel Visual Fortran Compiler for 64-bit apps\n", " --fcompiler=mips MIPSpro Fortran Compiler\n", " --fcompiler=none Fake Fortran compiler\n", " --fcompiler=sun Sun or Forte Fortran 95 Compiler\n", "For compiler details, run 'config_fc --verbose' setup command.\n" ] } ], "prompt_number": 16 }, { "cell_type": "code", "collapsed": false, "input": [ "%f2py_help --compiler" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "List of available compilers:\n", " --compiler=bcpp Borland C++ Compiler\n", " --compiler=cygwin Cygwin port of GNU C Compiler for Win32\n", " --compiler=emx EMX port of GNU C Compiler for OS/2\n", " --compiler=intel Intel C Compiler for 32-bit applications\n", " --compiler=intele Intel C Itanium Compiler for Itanium-based applications\n", " --compiler=intelem Intel C Compiler for 64-bit applications\n", " --compiler=mingw32 Mingw32 port of GNU C Compiler for Win32\n", " --compiler=msvc Microsoft Visual C++\n", " --compiler=pathcc PathScale Compiler for SiCortex-based applications\n", " --compiler=unix standard UNIX-style compiler\n" ] } ], "prompt_number": 17 }, { "cell_type": "code", "collapsed": false, "input": [], "language": "python", "metadata": {}, "outputs": [], "prompt_number": 17 } ], "metadata": {} } ] }