The code structure

Currently (since milestone 0.1.0), the MGv5 code is structured as follow. Make sure your code fits in this structure (i.e., appears as a module, package, ...) and if not, please contact the whole team before any big structure modification. The content of the root directory (the first directory in the hierarchy) is the as follow:

• apidoc: the directory containing the documentation generated automatically by Epydoc (class hierarchies, doc strings, ...). It is empty in bazaar and filled automatically with a script in the released versions. Never add a file here.
• bin: the directory containing all the main executables, directly ran by the user (including the standard mg5 executable). Those scripts should be executable and should not contain actual code, but only brief calls to the madgraph library. Since adding too many scripts here might confuse beginners, always ask the team opinion before doing so.
• doc: the official documentation for the package, written by humans for humans. Also contains tutorials, examples, ...
• madgraph: the main package, which is completely independent of the rest so that it can be installed as a library in a local python distribution. Never add modules directly in this directory, but select an existing subdir or create a new one.
  • core: the main package containing all the core routines/objects of madgraph (diagram generation, color calculations, ...)
  • interface: all scripts dealing with UI, command line, web based or graphical
  • iolibs: all scripts dealing with reading and writing files with a given format
  • your_package: it’s the right place to create new packages if your module does not fit in the existing ones
• tests: the main test package
  • acceptance_tests: contains all the acceptances tests, i.e., test dedicated to verify the code behaves correctly for generic requests. Feature oriented.
  • unit_tests: package containing all unit tests, i.e., low level tests dedicated to a particular part of the code (a class, a function, ...). It has an internal structured reproducing the madgraph library structure. All files containing tests should be named like test_testedmodule.py.
  • parallel_tests: contains script to run mg5 in parallel with other softwares (e.g., mg4, sherpa, ...) and compare results automatically.
  • test_manager.py: script allowing one to run all tests or well defined subsets in one single command. It’s the preferred way to interact with the test package.
• AUTHORS, LICENSE, VERSION: information about authors, license and version. Those files are in fact in the madgraph subdirectory, but there is a symbolic link to them in the root directory. The VERSION file has a fixed format such that the version/date information can be accessed by the various scripts.
• INSTALL, README: files giving summarized information on how to install and run mg5
• setup.py: the distutils setup file to build the madgraph library (if necessary, e.g., if it contains parts written in C) and install it locally (installation is not strictly required, but convenient when using mg as a development framework).

Regarding module import strategy, ALL module should import other madgraph modules after built-in modules using, for example

import madgraph.core
import madgraph.iolibs.files as files
from madgraph.interface.cmd_interface import MadGraphCmd

So, the root directory is supposed to appear in the PYTHONPATH. Scripts for direct interaction with users (like mg5) should always ensure that. NEVER use other techniques (relative imports, ...) since this one guarantees future portability. Test modules (and only them!!!) can access the tests package using, for example,

import tests.unit_tests.core as test_core

Notice that Python tests for the presence of init.py files to distinguish between directories and packages (which can be imported with import). Those files should be empty or contain a short piece of code that should be run before all other package modules. Don't remove them except if you know what you are doing.