==================================================
Modular Electromagnetic Inversion Software (ModEM)
==================================================

AUTHORS

  Gary Egbert, Anna Kelbert & Naser Meqbel
  College of Earth, Ocean and Atmos. Sciences
  104 CEOAS Admin. Bldg.
  Oregon State University
  Corvallis, OR 97331-5503
  
  E-mail:  egbert@coas.oregonstate.edu                                      
  Fax:     (541) 737-2064
  Ph.:     (541) 737-2947                                        
  http://www.coas.oregonstate.edu

==================================================

OBTAINING THE SOFTWARE

The Software (specifically, 2D and 3D MT modelling and inversion codes) are 
available for non-commercial and academic use subject to the license agreement 
in the attached Copyright statement. Implementations for other EM problems
within the framework of ModEM are currently not available for distribution.

The latest stable version of ModEM is available at our Subversion repository.
Please see below for details. Please contact the authors to obtain a username
and password to the repository. Alternatively, the authors may be willing to
provide a packaged archive or an executable.

==================================================

INSTALLATION

  To compile 3D MT:
  > cd f90; cp Makefile3d Makefile; make

  To compile 2D MT:
  > cd f90; cp Makefile2d Makefile; make
  
  The makefiles may also be generated with the Configure scripts, as follows:
  > ./Configure.3D_MT.GFortran Makefile release
  
  and
  > ./Configure.2D_MT.GFortran Makefile release
  
  Configure scripts are provided for the following compilers: 
    Portland Group, Intel, G95, GFortran

  The programs are parallelized with MPI. To compile with MPI, reconfigure. 
  E.g.,
  > ./Configure.3D_MT.Intel Makefile MPI

  Parallel configuration has only been tested with Portland Group and Intel.
  Compilers and linked libraries may be modified in the Configure scripts, or
  directly in the Makefiles. Configure scripts have to be rerun if the module
  usage dependencies change or if new source code is added.
  
  Running the programs with command line arguments as follows
  > ./Mod3DMT

  and
  > ./Mod2DMT
  will print the basic usage summary on screen. That should get you started.

  Subdirectory ModEM/examples contains sample input files with instructions.
  These should be sufficient to test your installation.

  At this time, we are not able to provide a thorough documentation. However,
  please refer to ModEM/doc subdirectory for further information about ModEM.

==================================================

BUG REPORTS AND FEATURE REQUESTS

If you find a reproducible bug, please let us know. The authors will try to
reproduce and eliminate the bug. Please note that we make no committment as
to the time frame.

Feature requests will be noted and possibly implemented sooner or later.
The users are welcome to work with us to improve specific features of ModEM.
Any such improvements will be subject to the Copyright statement as attached.

==================================================

UPDATING THROUGH SUBVERSION ON LINUX OR MAC

This note explains how to set up your computer to always have the latest
version of ModEM. You will need a Subversion client; we suggest that you
install CollabNet Subversion [http://www.collab.net/downloads/subversion].

A copy of ModEM may be obtained through Subversion version control system:
> svn checkout http://mt.coas.oregonstate.edu/svn/ModEM/branches/stable ModEM

Then, to update your software at any time, type:
> svn update

Always make sure to save your changes before updating. You could check for
changes by typing
> svn status

The command
> svn log
will let you view the comments on any recent modifications at the repository.
These may also be viewed by pointing your browser to the website:
http://mt.coas.oregonstate.edu/viewvc/ModEM/branches/stable

We recommend that you check this out periodically for bug fixes. Any changes
in the user interface will be thoroughly documented there. This way, you will
be forewarned of these before you update your version of the software.

==================================================

UPDATING THROUGH SUBVERSION ON WINDOWS

We suggest that you install TortoiseSVN [http://tortoisesvn.net/downloads].
The installer is self-explanatory and will require you to close almost all 
programs and restart the computer.

Create a directory where you'd like the code to reside.
Right-click on that directory and choose 'SVN Checkout'

Type the URL of ModEM repository:
http://mt.coas.oregonstate.edu/svn/ModEM/branches/stable
and click 'OK'

To fetch the latest version of the code at any time, right click on the 
directory and choose 'SVN update'.

Always make sure to save your changes before updating. If you've made 
temporary changes, do 'TortoiseSVN -> Revert' before running 'SVN update'.
This will not affect the new files you may have added to this directory.

The command 'TortoiseSVN -> Show Log' will let you view the comments on any 
recent modifications at the repository.
These may also be viewed by pointing your browser to the website:
http://mt.coas.oregonstate.edu/viewvc/ModEM/branches/stable

We recommend that you check this out periodically for bug fixes. Any changes
in the user interface will be thoroughly documented there. This way, you will
be forewarned of these before you update your version of the software.
   
==================================================

IMPORTING THROUGH ECLIPSE EDITOR

For users of Eclipse editor, it is also possible to import the ModEM project
into Eclipse directly from its Subversion repository. Here is how.

1) In Eclipse, install Photran and Subeclipse plugins using
   Help -> Software Updates -> Find and Install
2) Go to New -> SVN -> Checkout Projects from SVN
3) Type in repository location
   http://mt.coas.oregonstate.edu/svn/ModEM/branches/stable
4) If possible to check out the subdirectory f90 as a new project, do so.
   This option is provided if .project file is not present in the directory.
   Otherwise, just check out the subdirectory f90.
5) If checking out as a new project, select
   Fortran Project -> Makefile Project -> GCC Tool Chain 

==================================================

CONTRIBUTIONS TO THE SOFTWARE

If you have made contributions or edits (such as bug fixes) that you would like 
propagated to the repository, please contact us. Usually, we would like to test
your changes before propagating them to the repository. 

In rare cases, you will be given username and password that will allow you to 
commit your Software changes directly. The first time you attempt a commit, you 
will be asked to provide these.

Useful commands for code editing include:
> svn mv file1 file2
> svn add new_file new_dir
> svn rm old_file
> svn status

Your changes may be committed to the repository using:
> svn commit -m 'My commit message'
> svn commit -F msg_file
on Linux/Mac, or by choosing 'TortoiseSVN -> SVN Commit' on Windows.

Please refer to Subversion manual [http://svnbook.red-bean.com] for details.

Commit is non-reversible, so always double-check your changes first. It is good 
practice to always update (or revert and update) before making significant 
changes and committing.

=======================================================================
OR LEGACY README.tex 
=======================================================================


ModEM Fortran Source — Build Instructions
==========================================

The ModEM v6.2.6 Fortran sources are already bundled in this directory:

  _source/2D/   — Mod2DMT (2-D MT serial)
  _source/3D/   — Mod3DMT (3-D MT serial + MPI)

You do NOT need the external ModEMv626/ folder to compile.
Just install the prerequisites and run make.

Step 1 — Install prerequisites
--------------------------------
Ubuntu/Debian:
  sudo apt install gfortran liblapack-dev libblas-dev

CentOS/RHEL:
  sudo yum install gcc-gfortran lapack-devel blas-devel

For MPI builds (3D only — recommended for production):
  sudo apt install libopenmpi-dev   # or: module load mpi (HPC clusters)

Step 2 — Compile
-----------------
Serial (2D):
  cd pycsamt/models/modem/_source/2D/
  make

Serial (3D):
  cd pycsamt/models/modem/_source/3D/
  make

MPI-parallel (3D — recommended for production runs):
  cd pycsamt/models/modem/_source/3D/
  make mpi

Intel compiler:
  make intel          # serial (2D or 3D)
  make intel_mpi      # MPI, 3D only

After compilation, copy or symlink the binary to a directory on PATH:
  ln -s $(pwd)/Mod3DMT ~/bin/Mod3DMT
  ln -s $(pwd)/Mod2DMT ~/bin/Mod2DMT   # 2D build

The pycsamt runner locates the binary via PATH or the absolute path
stored in ModEmConfig.binary_3d / ModEmConfig.binary_2d.

Updating sources (advanced)
-----------------------------
If you obtain a newer ModEM release, run install_sources.sh to refresh:

  bash pycsamt/models/modem/_source/install_sources.sh /path/to/newer/ModEM

This overwrites the bundled sources with the new version.

References
----------
Egbert, G.D. & Kelbert, A. (2012). Computational recipes for electromagnetic
inverse problems. Geophysical Journal International, 189(1), 251-267.

Kelbert, A., Meqbel, N., Egbert, G.D., Tandon, K. (2014). ModEM: A modular
system for inversion of electromagnetic geophysical data.
Computers & Geosciences, 66, 40-53.
