Skip to content

Commit 9a07f06

Browse files
vincefnvincefn
committed
Add Fox documentation, converted from the legacy wiki pages
1 parent f5ec9d3 commit 9a07f06

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+2329
-0
lines changed

‎Fox/doc/.readthedocs.yaml

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
version: 2
2+
3+
build:
4+
os: "ubuntu-22.04"
5+
tools:
6+
python: "3.12"
7+
8+
sphinx:
9+
configuration: Fox/doc/conf.py

‎Fox/doc/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎Fox/doc/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎Fox/doc/source/_static/Fox.png

64.7 KB
Loading

‎Fox/doc/source/_static/css/custom.css

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*default is 60em*/
2+
.bd-main .bd-content .bd-article-container {
3+
max-width: 120em;
4+
}
5+
6+
/* default is 88rem*/
7+
.bd-page-width {
8+
max-width: 120em;
9+
}
10+
11+
/* Larger header/navbar for Fox logo*/
12+
.navbar-brand img{
13+
height: auto;
14+
}
15+
16+
.navbar {
17+
height: 6em;
18+
}

‎Fox/doc/source/biblio-structures.rst

+613
Large diffs are not rendered by default.

‎Fox/doc/source/biblio.rst

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. _biblio:
2+
3+
*************************
4+
Bibliography & Citing Fox
5+
*************************
6+
7+
Authors
8+
=======
9+
10+
FOX was developed by **Vincent Favre-Nicolin**, in collaboration with **Radovan Cerny** at the Laboratory of Crystallography of the `University of Geneva, Switzerland <http://www.unige.ch/>`_, with support from the `Swiss National Science Foundation <http://www.snf.ch/>`_ (project #21-53847.98, 2000-2001).
11+
12+
Vincent Favre-Nicolin continued the project (but not as a main research project) while working at `ESRF` (2001-2002),
13+
at the `Université Grenoble Alpes <https://univ-grenoble-alpes.fr>`_ (2002-).
14+
15+
*Note*: **This is a free, open-source project**. If there is something that you would like to see in it, you can contribute to it by submitting bugs, new code, help improving the documentation. See the `github project page <https://github.com/vincefn/objcryst>` for more details about the source code.
16+
17+
References for Fox
18+
==================
19+
The references for Fox are (*at least give the **first** reference in any article*, and if possible the website address:
20+
21+
* `J. Appl. Cryst. 35 (2002), 734-743 <http://scripts.iucr.org/cgi-bin/paper?vi0168>`_, V. Favre-Nicolin and R. Cerny, *FOX, 'free objects for crystallography': a modular approach to ab initio structure determination from powder diffraction*
22+
23+
* **Fox**, *Free Objects for Crystallography*, https://github.com/vincefn/objcryst
24+
25+
Other articles dealing with Fox include:
26+
27+
* `Z. Kristallogr. 219 (2004) 847–856 <http://dx.doi.org/10.1524/zkri.219.12.847.55869>`_, V. Favre-Nicolin and R. Cerny. *A better FOX: using flexible modelling and maximum likelihood to improve direct-space ab initio structure determination from powder diffraction*
28+
29+
* `Powder Diffraction 20 (2005) 359-365 <http://dx.doi.org/10.1154/1.2135314>`_, R. Cerny and V. Favre-Nicolin. *FOX: A friendly tool to solve nonmolecular structures from powder diffraction*
30+
31+
* `Z. Kristallogr. 222 (2007) 105-113 <http://dx.doi.org/10.1524/zkri.2007.222.3-4.105>`_, R. Cerny and V. Favre-Nicolin. *Direct space methods of structure determination from powder diffraction: principles, guidelines and perspectives*.
32+
33+
34+
.. toctree::
35+
:maxdepth: 1
36+
:caption: List of structures solved using Fox (2002-2012)
37+
38+
biblio-structures

‎Fox/doc/source/changelog.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. _changelog:
2+
3+
Changelog
4+
=========
5+
6+
.. include:: ../../ChangeLog.txt

‎Fox/doc/source/compile-linux.rst

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
.. _compile_linux:
2+
3+
Compiling Fox under Linux
4+
=========================
5+
6+
Requirements
7+
------------
8+
To install F.O.X. under Linux, you will need:
9+
* standard development packages (gcc,..)
10+
* OpenGL development libraries, e.g. `libopengl-dev`
11+
12+
You will also need more specific dependencies:
13+
* wxGTK (>=3.0.2)
14+
* newmat
15+
* freeglut
16+
* fftw3 (development library)
17+
18+
Not that the latter can be automatically donwloaded and linked statically as part of the Fox installation,
19+
but you can use the system libraries when they are available.
20+
21+
Debian/Ubuntu
22+
^^^^^^^^^^^^^
23+
Install the following packages (22.04): ``gcc g++ libwxgtk3.0-gtk3 ibwxgtk3.0-gtk3-dev freeglut3 freeglut3-dev``
24+
25+
Download Fox
26+
------------
27+
Fox release from github
28+
^^^^^^^^^^^^^^^^^^^^^^^
29+
Get the Fox.tar.bz2 from `GitHub <https://github.com/vincefn/objcryst/releases>`_,
30+
and uncompress:
31+
32+
.. code-block:: shell
33+
34+
tar -xjf Fox-VERSION.tar.bz2
35+
36+
Get the latest Fox from the git repository
37+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38+
39+
.. code-block:: shell
40+
41+
git clone https://github.com/vincefn/objcryst.git
42+
mv objcryst Fox
43+
cd Fox/ObjCryst
44+
ln -sf rules-gnu.mak rules.mak
45+
cd ../Fox
46+
ln -sf gnu.mak Makefile
47+
48+
Compile & install Fox
49+
---------------------
50+
51+
To compile and install Fox, go to the Fox/Fox subdirectory (or Fox-VERSION/Fox/), and then type:
52+
53+
.. code-block:: shell
54+
55+
make shared=1 # See note below about shared libraries options
56+
sudo make install #(for this last step you must be root).
57+
58+
**Note 1**: there are several options for the ```make``` command:
59+
60+
If fftw, wxgtk (>=3.0.2), freeglut or newmat are already available as shared libraries on your computer,
61+
you can use them without recompiling them. You can just append ```shared-wxgtk=1```, ```shared-glut=1```,
62+
``shared-fftw=1``` and ```shared-newmat=1```.
63+
64+
If you have all five shared libraries (as possible for Debian and Ubuntu), just use ```shared=1```. Examples:
65+
66+
.. code-block:: shell
67+
68+
make shared-wxgtk=1 shared-glut=1 shared-fftw=1
69+
70+
make shared=1
71+
72+
73+
Fox will be installed in /usr/local/bin/Fox. Otherwise the compiled file is in the `src/Fox` subdirectory.
74+
75+
**Note 2**: if during the early stages of the compilation (when freeglut is compiled), you get
76+
an error message about ```libGL.la```, this can mean that ```libGL.la``` is not in the same
77+
directory as other x11 libraries. On my computer, where ```libGL.la``` is provided by the nVidia
78+
installer, I needed to do "```ln -s /usr/lib/libGL.la /usr/X11R6/lib/```".
79+
80+
Compile & install Fox without GUI (Fox-nogui)
81+
---------------------------------------------
82+
83+
It is possible to compile a version of Fox that does not use a GUI and can only be used
84+
from the command-line. This is useful if you want to use Fox on a cluster.
85+
To do that just you just need to compile the ```Fox-nogui``` target:
86+
87+
.. code-block:: shell
88+
89+
tar -xjf Fox-VERSION.tar.bz2
90+
cd Fox-VERSION
91+
cd Fox
92+
make Fox-nogui shared=1
93+
94+
The resulting application is ```src/Fox-nogui```
95+
96+
Note that when switching from building ```Fox``` to building ```Fox-nogui``` (and vice-versa)
97+
you must do a ``` make tidy``` first in the build directory.
98+
99+
Compiling an optimized version of Fox
100+
-------------------------------------
101+
*Note: the instructions below are most likely obsolete as they were written > 15 years ago, they are
102+
left just in case they can be usefu. Feel free to experiment and propose an update !*
103+
Compile options
104+
^^^^^^^^^^^^^^^
105+
The first set of optimizations can be activated by using processor-specific optimizations.
106+
If you edit the ```Fox/ObjCryst/rules.mak``` file, and search for the part where the ```CPPFLAGS``` are defined:
107+
108+
.. code-block:: shell
109+
110+
CPPFLAGS = -O3 -w -ffast-math -fstrict-aliasing -pipe -fomit-frame-pointer -funroll-loops
111+
112+
*Auto-vectorization*: starting with gcc 4.0.0, it is possible to automatically **vectorize** some loops:
113+
append ```-ftree-vectorize``` to the ```CPPFLAGS``` options to do that
114+
(see the examples commented out in the ```rules.mak``` file).
115+
116+
Profile driven optimizations
117+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
118+
119+
Fox can be further optimized by making "test runs" which are used to give hints to the compiler
120+
on how to best optimize the code. To do this you (i) compile Fox by enabling the "recording"
121+
of the optimization, then (ii) you run a few optimizations, then (iii) you recompile using the
122+
recorded profile. To do that from the Fox subdirectory, do:
123+
124+
.. code-block:: shell
125+
126+
make clean
127+
make Fox profile=2
128+
src/Fox --nogui example/pbso4-joint.xml --randomize -n 50000 -o /dev/null
129+
src/Fox --nogui example/Cimetidine-powder.xml --randomize -n 50000 -o /dev/null
130+
src/Fox --speedtest
131+
make clean
132+
make Fox profile=3
133+
make install
134+
135+
This yields about 10% faster code.
136+
137+
If you also launch the Fox GUI and do a profile-fitting (between the 'profile=2' and 'profile=3' compilations),
138+
this will also **accelerate profile fitting and least squares operations**.

‎Fox/doc/source/compile-mac.rst

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. _compile_macos:
2+
3+
Compiling Fox under macOS
4+
=========================
5+
6+
Requirements
7+
------------
8+
* XCode
9+
10+
Other requirements (wxWidgets, fftw, cctbx, newmat) will be automatically downloaded and compiled.
11+
12+
Compile Fox
13+
-----------
14+
15+
* First download the linux package for Fox ```Fox-xxxx.tar.bz2``` from
16+
`GitHub <https://github.com/vincefn/objcryst/releases>`_, and uncompress it.
17+
* Go into the Fox/Fox subdirectory, then compile Fox using ```make -f macosx.mak dist```
18+
* You will get a disk image (\*.dmg) including the Fox application

‎Fox/doc/source/compile-windows.rst

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _compile_windows:
2+
3+
Compiling Fox on windows (windows 10 and visual studio 2019 instructions)
4+
=========================================================================
5+
* Get **Visual Studio 2019** from https://visualstudio.microsoft.com/fr/downloads/.
6+
Install it with C++ desktop tools, include CLI (command=line interface), C++ clang
7+
* Download **objcryst** from git (https://github.com/vincefn/objcryst), rename the root 'objcryst' directory to 'Fox'
8+
* Download **cctbx.tar.bz2** and **newmat.tar.bz2** (from https://github.com/vincefn/objcryst/releases/tag/v2021-3rdPartyLibs)
9+
in the Fox directory and uncompress them (e.g. with 7-zip)
10+
* Delete the Fox/cctbx/include/boost directory
11+
* Download **boost** 1.74 (7z format) from https://sourceforge.net/projects/boost/files/boost/1.74.0/.
12+
Unzip in Fox and rename the directory to 'boost'
13+
* Open the visual studio command prompt. In the Fox/boost directory, run ```bootstrap``` and then
14+
```b2 --build_dir=..\boost_build toolset=msvc release threading=multi --build_type=complete```.
15+
* Next download the **wxwidgets 3.1.4** installer and run it with default installation,
16+
select the installation directory as Fox/wxWidgets
17+
* Open the visual studio command prompt. In Fox\wxWidgets\build\msw, run
18+
```nmake /f makefile.vc BUILD=release RUNTIME_LIBS=static``` as per https://github.com/wxWidgets/wxWidgets/blob/v3.1.2/docs/msw/install.md
19+
* Download **fftw-3.3.5-dll32.zip** from http://www.fftw.org/install/windows.html, uncompress it as Fox/fftw
20+
* In a visual studio command prompt, in the Fox/fftw directory, execute ```lib /def:libfftw3f-3.def```
21+
* Open **Fox_vc12.sln** from Fox/Fox/, and then you can build Fox in debug or release version

‎Fox/doc/source/compile.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _compile:
2+
3+
Compiling Fox
4+
=============
5+
6+
.. toctree::
7+
compile-linux
8+
compile-mac
9+
compile-windows

‎Fox/doc/source/conf.py

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'Fox'
10+
copyright = '2024, Vincent Favre-Nicolin'
11+
author = 'Vincent Favre-Nicolin'
12+
release = '2024.x'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = []
18+
19+
templates_path = ['_templates']
20+
exclude_patterns = []
21+
22+
# -- Options for HTML output -------------------------------------------------
23+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
24+
25+
html_theme = "pydata_sphinx_theme"
26+
html_static_path = ['_static']
27+
html_logo = "_static/Fox.png"
28+
html_css_files = ['css/custom.css']
29+
30+
# Not sure what all these actually do
31+
html_theme_options = {
32+
"show_nav_level": 2,
33+
"navigation_depth": 1,
34+
"navbar_align": "left",
35+
# "primary_sidebar_end": ["indices.html", "sidebar-ethical-ads.html"]
36+
}
37+
38+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
39+
html_sidebars = {
40+
"**": ["globaltoc.html", "sidebar-nav-bs"],
41+
# "**": ["localtoc.html"],
42+
# "**": ["sidebar-nav-bs"],
43+
# "<page_pattern>": ["index", "manual-intro", "tutorials", "manual"]
44+
}

0 commit comments

Comments
 (0)