1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
.. _installing:
**************************
Installing the application
**************************
.. contents:: :local:
Bumps |version| is provided in a self-contained Python environment:
- Windows installer: :slink:`%(winexe)s`
- Apple installer: :slink:`%(macapp)s`
- Apple (Intel) installer: :slink:`%(imacapp)s`
- Linux self-contained package: :slink:`%(linuxapp)s`
The Windows installer installs to the `AppData/Local` directory by default,
and adds a shortcut to the Start menu, optionally adding a desktop shortcut.
It also provides an uninstaller through the Control Panel (add/remove programs)
The Apple .dmg installer unpacks to the Applications directory. You can
start the application by double-clicking on the `bumps_webview.app`.
To uninstall just drag the entire app to the trash from your finder.
For Linux (HPC), you can download the self-contained package and unpack it
to a directory of your choice. The package contains a python environment
with all the required dependencies, including the webview interface.
To run the application, change into the unpacked directory and run::
./bin/python -m bumps
For Debian/Ubuntu Linux, bumps is provided as a package [pre-1.0 as of this writing]::
sudo apt install python3-bumps
For other linux or for the latest version you will need to install bumps
as a python package.
Python install
==============
Bumps is available on `PyPI <https://pypi.org/project/bumps/>`_ so you can
install directly into a python environment with pip.
To avoid conflicts between python applications it is good practice to create
a separate python environment for each one.
We recommend using
`miniforge <https://github.com/conda-forge/miniforge/releases/latest>`_.
This installs a conda system with the "conda-forge" channel for packages.
Versions are available for Windows, MacOS and Linux.
To create your environment and install bumps use::
conda create --name bumps python
conda activate bumps
pip install bumps
You could instead download Python directly from
`Python.org <https://www.python.org/downloads/>`_.
Again, recommended practice is to use an isolated python environment::
python -m venv bumps
. bumps/bin/activate
pip install bumps
Running bumps
=============
Fitting problems in bumps are defined in python files or jupyter notebooks. You
can retrieve the example *curve.py* model
`here <https://github.com/bumps/bumps/blob/master/doc/examples/curvefit/curve.py>`_
To run the webview interface with your problem showing in a browser window use::
bumps curve.py
To run in batch mode with no interactive interface use::
bumps -b curve.py --store=session.hdf
This runs a complete fit, appending the results to the session file T1.hdf. To later
view the fit results use::
bumps --store=session.hdf
There are many command line options for controlling the fit. For a complete list use::
bumps -h
Jupyter notebooks
=================
The webview interface can be run inside a Jupyter notebook. This allows you to interact with the server
from within the notebook, providing a more integrated experience for users who are already working in a Jupyter environment.
You will need to set up Jupyter. You can install jupyter into your bumps
environment with pip and run the Jupyter server from there. If you are using
jupyterhub, you can install and run ipykernel in your bumps environment to make
it available::
pip install ipykernel
python -m ipykernel install --user --name bumps --display-name "bumps"
If running on colab or similar, then you can install bumps from within a
notebook cell using pip:
%pip install bumps
To start webview, use the following code cell::
import asyncio
from bumps.webview.server import start_bumps_server, api
# Start the server
await start_bumps_server()
A link to the server will be printed in the notebook output. You can open this link in a browser to access the server.
In a different cell you can define a problem and load it into the server using the `api` module::
# Define a problem
from bumps.fitproblem import FitProblem
model = MyFitnessClass()
...
problem = FitProblem([model])
await api.set_problem(problem)
Fast Stepper for DREAM on MPI
=============================
When running DREAM on larger clusters, we found a significant slowdown as the
number of processes increased. This is due to Amdahl's law, where the run
time speedup is limited by the slowest serial portion of the code. In our
case, the DE stepper and the bounds check. Compiling this in C with OpenMP
allows us to scale to hundreds of nodes until the stepper again becomes a
bottleneck.
The following command should build the fast stepper binary module::
python -m bumps.dream.build_compiled
If you have installed from source, you must first check out the random123 library::
git clone --branch v1.14.0 https://github.com/DEShawResearch/random123.git bumps/dream/random123
python -m bumps.dream.build_compiled
If this fails you can try running the compiler directly. First find the path
to the bumps directory::
$ python -c "import bumps.dream; print(bumps.dream.__file__)"
#path/to/bumps/dream/__init__.py
Change into that directory and compile the module::
(cd path/to/bumps/dream && cc compiled.c -I ./random123/include/ -O2 -DMAX_THREADS=64 -fopenmp -shared -lm -o _compiled.so -fPIC)
Note: clang doesn't support OpenMP, so on macOS use::
(cd path/to/bumps/dream && cc compiled.c -I ./random123/include/ -O2 -DMAX_THREADS=64 -shared -lm -o _compiled.so -fPIC)
Make sure MAX_THREADS is at least the number of processors on your system
otherwise you will need to set :code:`OMP_NUM_THREADS=MAX_THREADS` in your
environment before running bumps.
|
