Troubleshooting / FAQ

A short list of the most common questions and pitfalls. Many of these are also mentioned in context in the Installation and Tutorial pages; they are collected here for convenience.

Does raypyng work on Windows?

No, not for running simulations. Driving RAY-UI from Python relies on RAY-UI’s background mode, which is the channel raypyng uses to send commands and read back results. RAY-UI does not offer a background mode on Windows, so there is no way for raypyng to communicate with it. The simulation workflow is therefore supported on Linux and macOS only. Pure-Python helpers that do not launch RAY-UI (reading/writing .rml files, the standalone Dipole spectrum, the diode conversion, …) may still work on Windows.

Do I need the `if name == 'main':` guard?

Yes, on macOS. raypyng runs the simulations in parallel through Python’s multiprocessing. On macOS the worker processes are created with the spawn start method, which re-imports your script in every worker. If the call to sim.run() is not protected by if __name__ == '__main__':, each worker re-runs it on import, leading to runaway process creation and a RuntimeError about the bootstrapping phase.

On Linux the default start method is fork, which does not re-import the script, so the guard is not strictly required there — but adding it is harmless and keeps the same script working on both supported platforms.

I get a `RuntimeError` about “bootstrapping phase”

This is the symptom of the missing guard described above. Wrap your simulation setup and the sim.run() call in if __name__ == '__main__':.

On macOS, “Ray-UI is not responding” / “Ray-UI quit unexpectedly”

This is harmless and can be ignored. While simulations run, macOS may sporadically show a dialog saying that Ray-UI is not responding or quit unexpectedly. It is just macOS noticing that the headless RAY-UI instances are started and stopped rapidly. The simulations are not affected and complete normally — simply dismiss the dialogs.

Do I need to install xvfb?

Only on Linux. On Linux, xvfb provides the virtual X11 framebuffer that lets RAY-UI run headless, and raypyng uses xvfb-run automatically. On macOS xvfb is not needed and must not be installed; raypyng skips it automatically and the hide parameter is simply ignored.

raypyng cannot find RAY-UI

By default raypyng searches the standard installation folders. If your installation is elsewhere, pass the path explicitly:

sim = Simulate('rml/dipole_beamline.rml', hide=True, ray_path='/path/to/RAY-UI')

On macOS the installer creates a Ray-UI.app bundle, so the installation folder is the directory that contains Ray-UI.app (for example ~/Applications/RAY-UI), not the .app itself.

How many parallel instances should I use?

The multiprocessing argument to sim.run() controls how many RAY-UI instances run in parallel:

an integer >= 1 — that exact number of instances,
"auto" — the minimum between the available CPU count and the available RAM in GB minus 2,
"max" — the minimum between the available CPU count and the available RAM in GB.

As a rule of thumb, do not use more instances than you have CPU cores. If your simulations use many rays, watch the RAM usage: if the machine runs out of memory the program may block or produce incorrect results. In that case reduce the number of parallel instances or the number of rays.

My simulations are slow

The speedup from running many RAY-UI instances in parallel is effective only when RAY-UI is not doing the analysis. Prefer letting raypyng analyze the results:

sim.analyze = False          # don't let RAY-UI analyze the results
sim.raypyng_analysis = True  # let raypyng analyze the results