Common Errors and Pitfalls

This page collects common errors and easy pitfalls encountered by beginners (and sometimes even advanced!) users of AMUSE. It is organized in a list of common mistakes and pitfalls, a selection of common error messages, which may not be easily decipherable and a list of code specific issues.

particle set attributes

Accessing an attribute of a particle set in memory currently returns a reference to the data:

x[5]=5 | units.m

will change particles[5].x. This is not the case for remote particle sets; in this case a reference to a copy of the data is returned. In older versions of AMUSE this was not the case: in memory sets also returned a reference to a copy. This is something to be aware of (especially with older scripts).

Closing file after reading a set

After reading more than approximately one thousand files with the function read_set_from_file you can run into a problem. This happens because this function keeps the file open for later operations. Normally this would not be necessary but you can trigger the close your file by adding the option: close_file, like so

particles= read_set_from_file('filename', 'amuse', close_file=True)

Getting information about code calls

You can turn on logging to get information about the calls to the community code interface functions, by putting the following at the start of your script:

import logging

This is especially useful to check the assumed call sequence.

Running interactive AMUSE session with mpiexec

In case you run AMUSE scripts with mpiexec (see  #how to install AMUSE), you need to add the -i option to run the AMUSE interactive session from the command line:

> mpiexec -i

Common mistakes and Pitfalls

Being written in Python, AMUSE not always behaves in a way that users may expect.

unit handling

an expression like:

>>> print 1.|units.m + 1.|units.m

will evaluate to an error message:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unsupported operand type(s) for +: 'base_unit' and 'float'

The reason for this is the low precedence of the '|' used for constructing quantities. The correct way to write the above is:

>>> print (1.|units.m) + (1.|units.m)

Liberal use of parentheses is recommended for unit expressions.

unit none

As of feb 2012 and for release versions after 5.1 arithmetic expressions with result in a quantity with unit.none will automatically drop the unit none. If you get an error in an existing script which converted to a float, e.g.:

>>> print ((1||
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'float' object has no attribute 'value_in'

remove the .value_in(unit.none) bit:

>>> print ((1||

rules for handling angular units

Angular units are defined as units.rad, units.deg and units.rev. These are dimensionless, so expressions with these will usually evaluate to float. In accordance with the definitions of the numpy trigonometric functions, floats are interpreted as having unit radians. Expressions with degrees and revolutions evaluate correctly:

>>> from amuse.units import units
>>> print 0.5* (1. | units.rev)
>>> print 2* (90. | units.deg)

in amuse.units.trigo there are definitions of "unit aware" trigonometric functions and conversion functions which do not care about the presence of an angular unit:

from amuse.units import trigo
>>> print trigo.sin(1.)
>>> print trigo.sin(1. | units.rad) 
>>> print trigo.to_deg(1. | units.rad) 
57.2957795131 deg
>>> print trigo.to_deg(1. ) 
57.2957795131 deg

frequency units

A similar issue arises when using frequency units, i.e. Hz. This is defined currently as 1 | units.s**-1 which is ambiguous:

>>> a= 1. | units.Hz
>>> print a.in_(units.rev/units.s)
0.159154943092 rev / s

which is the same (and formally wrong) as:

>>> a= 1. | units.rad*units.Hz
>>> print a.in_(units.rev/units.s)
0.159154943092 rev / s

A definition of Hz as rev/s would be better, but may also be confusing in some cases..

python lists and numpy arrays

Python lists and numpy arrays can both be used in AMUSE (e.g. in combination with units. Beware of the differences:

>>> print [0.] *3 |units.m
[0.0, 0.0, 0.0] m
>>> print numpy.array([1.]) *3 |units.m
[3.0] m

Common error message

AMUSE will often generate quite verbose error messages. We list here the most common error messages with their cause and solution. If you repeatedly encounter an error that is not listed here please join us on the  #amuse irc channel to discuss this.

  • " TypeError: unsupported operand type(s) for +: 'base_unit' and 'float' "
    this error indicates a syntax error writing an unit expression, see unit handling.
  • " ImportError: No module named amuse.units "
    If you try to start an amuse script and you get an import error, e.g.:
    > python
    Traceback (most recent call last):
      File "", line 3, in <module>
        from amuse.units import units
    ImportError: No module named amuse.units
    this often indicates that python can not find the amuse components. run through the script:
    > path/to/amuse/
    or set the PYTHONPATH environment variable to include the amuse src directory.
  • " The worker application does not exists, it should be at: ... "
    This error message is accompanied by a verbose error, e.g.:
    ./ examples/simple/
    Traceback (most recent call last):
      File "examples/simple/", line 99, in <module>
        run_mc(10000,Mcloud=1000. | units.MSun,Rcloud=1. | units.parsec)
      File "examples/simple/", line 59, in run_mc
      File "/data2/pelupes/amuse/amuse-new/src/amuse/community/fi/", line 1522, in __init__
        legacy_interface = FiInterface(mode = mode, **options)            
      File "/data2/pelupes/amuse/amuse-new/src/amuse/community/fi/", line 34, in __init__
        CodeInterface.__init__(self, name_of_the_worker = self.name_of_the_worker(mode), **options)
      File "/data2/pelupes/amuse/amuse-new/src/amuse/support/codes/", line 586, in __init__ = self.channel_factory(name_of_the_worker, type(self), **options)
      File "/data2/pelupes/amuse/amuse-new/src/amuse/support/codes/", line 553, in __init__
        self.full_name_of_the_worker = self.get_full_name_of_the_worker( legacy_interface_type)
      File "/data2/pelupes/amuse/amuse-new/src/amuse/support/codes/", line 463, in get_full_name_of_the_worker
        raise exceptions.CodeException("The worker application does not exists, it should be at: {0}".format(tried_workers)) The worker application does not exists, it should be at: ['/data2/pelupes/amuse/amuse-new/src/amuse/community/fi/fi_worker', '/data2/pelupes/amuse/amuse-new/src/amuse/support/codes/fi_worker']
    This may be caused by amuse not being compiled, type:
    > make 
    in the amuse root. Or it may be that compiling the code in question has failed. This latter may be caused by missing components which should be downloaded first or by an error encountered during the compilation. Downloadable components will be installed if you set the DOWNLOAD_CODES environment variable and do make in the AMUSE root. If the compilation of a code failed you can type:
    make name_of_the_code.code
    in the AMUSE root to get a hint of the reason why it failed.
  • " TclError: no display name and no $DISPLAY environment variable "
    This error occurs when matplotlib fails to open an interactive backend, for example when you're logged in to a machine remotely. If you want to use the interactive window, re-login and try enabling X11 forwarding with the -X option:
    > ssh -X user@remote_machine 
    On the other hand, if you don't need the interactive window and you only use matplotlib to save the plots to file, try using a different, non-interactive backend such as Agg (for PNGs), PDF, SVG or PS. The best way to make any of these the default is by creating a file called matplotlibrc in your current working directory, which contains a line selecting the backend of your choice:
    backend: Agg

Code specific issues

Although most codes have a similar interfaces, some codes have special features or options that you may need to be aware of.


Some modes of operation for Gadget are not accessible from within the AMUSE interface, but need to be set in the makefile_options file in the gadget /src directory.

gadget has the following predefined modes: periodic, nogravity, which you can use by starting up the interface with for example:


Sometimes you run into problems with timesteps which are too small. Check the value of parameter time_max and make sure it is not too big. It is also good practice to limit the internal gadget timestep (by setting parameter max_size_timestep) to be smaller than the timestep in your script. It is also a good idea to make the time_max an integer power of 2 multiple of the timestep in the script (internally gadget uses an integer timeline)


A common error is caused by the fact that Fi uses a fixed computational box (set by the parameter periodic_box_size, even if not using the periodic mode). This parameter is set to 300 in internal units by default, but can be set to any value. Recomendation is to set it explicitly.

If the box size is too small, or particles start to escape, this can lead to the error:

AmuseException: Error when calling 'get_position' of a 'Fi', errorcode is -1

Either increase the box size, or remove particles before they reach the boundary of the box.

Another issue to be aware of is the fact that SPH particles in Fi have a minimum density, and corresponding maximum smoothing length, of 1.e-6 in internal units. So care must be taken giving Fi a converter such that the density in internal units never (or rarely, for e.g. escaping particles) reach this low density. If you experience problems where the smoothing length that the code calculates is lower than you would expect (e.g. each particle has no neighbours), you can for example increase the spatial scale of the converter.

Fi has a hard coded limit on the number of particles (2M by default). This may show up unexpectedly when removing and adding a lot of particles. Particles are not removed inmediately but only at a recommit, and for performance reasons a recommit is not by default triggered in between adding and removing particles.

Distributed AMUSE

It can sometimes be tricky to setup the system for distributed AMUSE. It is recommended to read the  documentation, and carefully check the configuration.