Skip to content

Commit 4752169

Browse files
committed
update install doc
1 parent 38d689c commit 4752169

File tree

1 file changed

+72
-63
lines changed

1 file changed

+72
-63
lines changed

doc/installation.rst

Lines changed: 72 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Downloading and Installation
99
.. _PyPI: https://pypi.org
1010
.. _Conda: https://conda.io
1111
.. _Python.org: https://python.org/
12-
.. _Mambaforge Python: https://github.com/conda-forge/miniforge/releases
12+
.. _Miniconda Python: https://github.com/conda-forge/miniforge/releases
1313
.. _lmfit: https://lmfit.github.io/lmfit-py/
1414
.. _xraydb: https://xraypy.github.io/XrayDB/
1515
.. _Larch Releases (github.com): https://github.com/xraypy/xraylarch/releases
@@ -49,7 +49,7 @@ programming language and environment:
4949
There will not be any difference in the resulting code or packages when using
5050
these different methods. Each of these will result in a Python environment
5151
from which you can either use Larch and its GUI applications, or develop code
52-
with Larch. We recommend using the Binary installer on Windws, and the
52+
with Larch. We recommend using the Binary installer on Windows, and the
5353
installation scripts on macOS or Linux, unless you know that you want to
5454
install into an existing Python environment.
5555

@@ -81,11 +81,12 @@ called `xraylarch` in your home folder -- see platform-specific notes below.
8181

8282
.. note::
8383

84-
There can be no spaces in your username or the path in which Larch is
85-
installed.
84+
There can be no spaces in the path in which Larch is installed.
85+
(to be clear, this is common to other Python environments).
8686

87-
If you have a space in your Windows username, you can probably install
88-
to ``C:\Users\Public`` - that has worked for some people!
87+
If you have a space in your user name, you must install to a
88+
different location. Using ``C:\Users\Public`` has worked for many
89+
people.
8990

9091

9192
Installing with these installer programs should write to files only to
@@ -115,7 +116,10 @@ name has a space in it, you will probably need to install to
115116

116117
.. note: If you get prompted for an administrative password during the
117118
installation process, you should make sure you are installing to a
118-
folder that is writable by the user.
119+
folder that is writable by the user. The Larch install will
120+
install binary executables, but will write files only to the user
121+
folder.
122+
119123
120124
121125
Alternatively you can download the `GetLarch.bat`_ script, and run that by
@@ -144,6 +148,13 @@ it to install Larch. There are two important notes:
144148
installation process. If you get prompted for an Administrative password
145149
by the installer, go back and explicitly choose "Install only for me".
146150

151+
.. note::
152+
153+
After clicking through the options, the package installer will
154+
start installing and quickly get a point where it says the
155+
installation has about one minute remaining. This appears to be
156+
optimistic for about ten minutes. ;)
157+
147158
Alternatively you can download the `GetLarch.sh`_ script, and run that in a
148159
Terminal session (Applications->Utilities->Terminal). This will download,
149160
install, and configure the Larch package, with a result that is nearly
@@ -202,7 +213,7 @@ macOS), and then type::
202213
If this script fails, report it to the `Larch Github Issues`_ (including
203214
the error trace and the `GetLarch.log` file).
204215

205-
The scripts will download and install `Mambaforge Python`_ which uses Anaconda
216+
The scripts will download and install `Miniconda Python`_ which uses Anaconda
206217
Python and the `conda-forge` channel as the basis of an installation that will
207218
be essentially identical to the environment installed by the binary installers,
208219
that is, the whole environment is stored in a folder called `xraylarch` in your
@@ -215,19 +226,23 @@ installation.
215226
Installing into an existing Anaconda Python environment
216227
=========================================================
217228

218-
If are already using an existing `Anaconda Python`_, you may want to install
219-
Larch into that environment or create a new environment for it. This is
220-
definitely possible. Larch uses many of the common "scipy ecosystem"
221-
packages. The main packages that you may need to install that may not be
222-
installed are:
229+
If are already using an existing `Anaconda Python`_, you may want to
230+
install Larch into that environment or create a new environment for
231+
it. This is definitely possible. Larch uses many of the common
232+
"scipy ecosystem" packages. The main must-have packages are `numpy`,
233+
`scipy`, `matplotlib`, and `h5py`.
234+
235+
In addition, the following extra packages that you may need include:
223236

224237
* `wxpython`: needed for all plotting, graphics and GUI applications.
225238
* `pymatgen`: needed for handling CIF files to generate Feff input files.
226239
* `openbabel`: needed for converting some structure files to Feff input files.
227240
* `tomopy`: needed only for reconstructing X-ray fluorescence tomography.
241+
* `scikit-learn`: needed for advanced regression methods.
242+
228243

229-
To be clear, much of the core Larch functionality can be used as a library
230-
without these packages installed, but especially `wxpython` and `pymatgen` are
244+
To be clear, much of the core Larch functionality can be used without
245+
these packages as a library. But `wxpython` and `pymatgen` are
231246
heavily used and should be installed.
232247

233248
There is a `conda-forge` package for X-ray Larch, so from a shell it may be
@@ -245,10 +260,9 @@ infrastructure and then install xraylarch with pip:
245260

246261
.. code:: bash
247262
248-
mamba create -y --name xraylarch python=>3.11.5 scipy mkl_fft h5py matplotlib pandas
263+
mamba create -y --name xraylarch python>=3.12.8
249264
mamba activate xraylarch
250-
mamba install -y -c conda-forge wxpython pymatgen jupyter "notebook<7.0"
251-
mamba install -y -c conda-forge scikit-image scikit-learn pycifrw plotly fabio pyfai
265+
mamba install -y -c conda-forge numpy==1.26 scipy>=1.14 matplotlib>=3.8 h5py>=3.10 wxpython>=4.2.1 mkl_fft
252266
mamba install -y -c conda-forge openbabel tomopy # <- optional packages
253267
pip install "xraylarch[larix]"
254268
@@ -259,12 +273,17 @@ infrastructure and then install xraylarch with pip:
259273

260274
.. note::
261275

262-
Jupyter notebook version 7 and later does not work with plotly, and
263-
specifically with the example Jupyter notebooks use X-ray Larch.
276+
Jupyter notebook version 7 and later does not work with Plotly
277+
version 5. At this writing, Plotly 6 is reported to work, but is
278+
not released yet. This may impact working with X-ray Larch in
279+
Jupyter notebooks.
264280

265281

266-
Since the `PyPI_` packages are the main release package, this method may better
267-
ensure that you get the latest version compared to installing the `conda-forge` package.
282+
Many of the packages needed can be installed either as Anaconda
283+
packages, or as plain Python packages from PyPI, and with the `pip`
284+
command. Since the `PyPI`_ packages are the main release package,
285+
this method may better ensure that you get the latest version compared
286+
to installing the `conda-forge` package.
268287

269288

270289
Finally, no matter how you install Larch, you can run
@@ -287,38 +306,36 @@ from `PyPI`_, so that a simple
287306
288307
pip install xraylarch
289308
290-
shoould work. Starting with version 0.9.73 9November, 2023), this command will
291-
work to install a fairly bare-bones set of tools -- the basic xraylarch
292-
library, without requiring the packages needed to make any of the GUIs work.
293-
294-
In order to get the GUI-needed package, you could install with
309+
should work, but will install a fairly bare-bones set of tools -- the
310+
basic xraylarch library, without requiring the packages needed to make
311+
any of the GUIs work. In order to get the GUI-needed package, you
312+
could install with
295313

296314
.. code:: bash
297315
298-
pip install xraylarch[larix]
316+
pip install "xraylarch[larix]"
299317
300-
(Note, you may need to type ``pip install "xraylarch[larix]"`` in some shells
301-
and terminals). This will also install all of the `wxPython` packages needed
318+
This will also install all of the `wxPython` packages needed
302319
for the GUIs, as well as the libraries related to Jupyter.
303320

304-
The most notable missing binary package is the `wxPython` package on Linux.
305-
That means that if `wxPython` is not already installed, `pip` will try to
306-
compile it, which will almost certainly fail. This problem (which, in fairness
307-
to all involved, is very difficult to solve) is one of the main reasons we
308-
recommend using `Anaconda Python` - it provides this package in a consistent
309-
way. Anaconda Python also provides very good versions of almost all of hte
310-
"core scipy ecosystem" libraries. It also has good support for optional Intel
311-
Math Kernel libraries that will be used if available.
321+
The most notable missing binary package needed for xraylarch on PyPI
322+
is the `wxPython` package on Linux. That means that if `wxPython` is
323+
not already installed, `pip` will try to compile it, which will almost
324+
certainly fail. This is one of the main reasons we recommend using
325+
`Anaconda Python` - it provides this package in a consistent
326+
way. Anaconda Python also provides very good versions of almost all of
327+
the "core scipy ecosystem" libraries and has good support for optional
328+
Intel Math Kernel libraries that will be used if available.
312329

313330
But, if you are not using Linux, or are using a system-provided Python that
314331
includes wxPython (and has it installed), it should be possible to install a
315332
runnable Larch library with
316333

317334
.. code:: bash
318335
319-
pip install xraylarch
336+
pip install "xraylarch[larix]"
320337
321-
There are other optional addons that can be installed with Larch, such as
338+
There are other optional add ons that can be installed with Larch, such as
322339

323340
.. code:: bash
324341
@@ -357,20 +374,10 @@ to `PyPI`_. This will allow updating can be done with
357374
pip install --upgrade xraylarch
358375
359376
360-
For versions up to 0.9.68, XAS Viewer (now Larix) and other Larch Applications
361-
would notify users as updates became available and prompt them to install the
362-
latest version.
363-
364-
.. note::
365-
366-
Automatic updates using Larix (was XAS Viewer) have been unreliable for a
367-
long time, and can cause a non-working system, especially on Windows.
368-
369-
370-
With version 0.9.70 and later, these notifications about updates are now
371-
informational and do not prompt for an immediate update. In addition, there is
372-
now a desktop shortcut called "Larch Updater" which will run the update `pip`
373-
command above.
377+
Larix and some other Larch Applications will notify you about
378+
available updates. To update, you an click on the "Larch Updater"
379+
desktop shortcut called, which will open a Shell and run the update
380+
`pip` command above.
374381

375382

376383
Installing the development version
@@ -429,7 +436,7 @@ the source repository with::
429436

430437
and then install with::
431438

432-
pip install -e .[all]
439+
pip install -e ".[all]"
433440

434441
This use of `pip` will install any requirements and Larch itself, but those
435442
should have been installed already when you installed. Depending on your
@@ -488,12 +495,14 @@ Conference Series, 430:012007 (2013). :cite:`larch2013`
488495
Funding and Support
489496
=======================
490497

491-
Larch development at the GeoScoilEnviroCARS sector of Center for Advanced
492-
Radiation Sources at the University of Chicago has been supported by the US
493-
National Science Foundation - Earth Sciences (EAR-1128799), and Department
494-
of Energy GeoSciences (DE-FG02-94ER14466). In addition, funding
495-
specifically for Larch was granted by the National Science Foundation -
496-
Advanced CyberInfrastructure (ACI-1450468).
498+
Larch development at the Center for Advanced Radiation Sources at the
499+
University of Chicago is currently supported by the National Science
500+
Foundation - Earth Sciences division and its SEES: Synchrotron Earth
501+
and Environmental Science (EAR-2223273). Earlier funding has come
502+
from GeoScoilEnviroCARS grant from NSF-EAR (EAR-1128799), and
503+
Department of Energy GeoSciences (DE-FG02-94ER14466). In addition,
504+
funding specifically for Larch was granted by the National Science
505+
Foundation - Advanced CyberInfrastructure (ACI-1450468).
497506

498507

499508
Acknowledgements
@@ -507,7 +516,7 @@ importantly, Larch would simply not exist without the long and fruitful
507516
collaboration we've enjoyed. Margaret Koker wrote most of the X-ray
508517
diffraction analysis code, and much of the advanced functionality of the
509518
GSECARS XRF Map Viewer. Mauro Rovezzi has provided the spec-data reading
510-
interface and the RIXS viewer. Tom Trainor had a very strong influence on
519+
interface and the RIXS viewer. Tom Trainor had a very strong influence on
511520
the original design of Larch, and helped with the initial version of the
512521
python implementation. Yong Choi wrote the code for X-ray standing wave
513522
and reflectivity analysis and graciously allowed it to be included and
@@ -530,7 +539,7 @@ conversations, and suggestions for making Ifeffit better, including on the
530539
ifeffit mailing list. Many of these contributions have found their way
531540
into Larch.
532541

533-
Larch uses X-ray scattering factors and cross-sections fro the `xraydb`_
542+
Larch uses X-ray scattering factors and cross-sections from the `xraydb`_
534543
library. This uses code to store and read the X-ray Scattering data from
535544
the Elam Tables was modified from code originally written by
536545
Darren S. Dale. Refined values for anomalous scattering factors there have

0 commit comments

Comments
 (0)