Skip to content

Commit 8c6c57e

Browse files
TieqiongTieqiong
committed
README
1 parent cd9415b commit 8c6c57e

File tree

1 file changed

+85
-83
lines changed

1 file changed

+85
-83
lines changed

‎README.rst

Lines changed: 85 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,41 @@
1-
.. image:: https://travis-ci.org/diffpy/diffpy.srfit.svg?branch=master
2-
:target: https://travis-ci.org/diffpy/diffpy.srfit
1+
|Icon| |title|_
2+
===============
33

4-
.. image:: https://codecov.io/gh/diffpy/diffpy.srfit/branch/master/graph/badge.svg
5-
:target: https://codecov.io/gh/diffpy/diffpy.srfit
4+
.. |title| replace:: diffpy.srfit
5+
.. _title: https://diffpy.github.io/diffpy.srfit
66

7+
.. |Icon| image:: https://avatars.githubusercontent.com/diffpy
8+
:target: https://diffpy.github.io/diffpy.srfit
9+
:height: 100px
710

8-
diffpy.srfit
9-
========================================================================
11+
|PyPi| |Forge| |PythonVersion| |PR|
1012

11-
Configurable code for solving atomic structures.
13+
|CI| |Codecov| |Black| |Tracking|
14+
15+
.. |Black| image:: https://img.shields.io/badge/code_style-black-black
16+
:target: https://github.com/psf/black
17+
18+
.. |CI| image:: https://github.com/diffpy/diffpy.srfit/actions/workflows/main.yml/badge.svg
19+
:target: https://github.com/diffpy/diffpy.srfit/actions/workflows/main.yml
20+
21+
.. |Codecov| image:: https://codecov.io/gh/diffpy/diffpy.srfit/branch/main/graph/badge.svg
22+
:target: https://codecov.io/gh/diffpy/diffpy.srfit
23+
24+
.. |Forge| image:: https://img.shields.io/conda/vn/conda-forge/diffpy.srfit
25+
:target: https://anaconda.org/conda-forge/diffpy.srfit
26+
27+
.. |PR| image:: https://img.shields.io/badge/PR-Welcome-29ab47ff
28+
29+
.. |PyPi| image:: https://img.shields.io/pypi/v/diffpy.srfit
30+
:target: https://pypi.org/project/diffpy.srfit/
31+
32+
.. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.srfit
33+
:target: https://pypi.org/project/diffpy.srfit/
34+
35+
.. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue
36+
:target: https://github.com/diffpy/diffpy.srfit/issues
37+
38+
SrFit - Structure refinement from diffraction data. Configurable code for solving atomic structures.
1239

1340
The diffpy.srfit package provides the framework for building a global optimizer
1441
on the fly from components such as function calculators (that calculate
@@ -32,115 +59,90 @@ obtain the total cost function. Additionally, diffpy.srfit is designed to be
3259
extensible, allowing the user to integrate external calculators to perform
3360
co-refinements with other techniques.
3461

35-
For more information about the diffpy.srfit library, see the users manual at
36-
http://diffpy.github.io/diffpy.srfit.
37-
38-
REQUIREMENTS
39-
------------------------------------------------------------------------
40-
41-
The diffpy.srfit package requires Python 3.5 or later or 2.7 and
42-
the following software:
62+
For more information about the diffpy.srfit library, please consult our `online documentation <https://diffpy.github.io/diffpy.srfit>`_.
4363

44-
* ``setuptools`` - software distribution tools for Python
45-
* ``NumPy`` - numerical mathematics and fast array operations for Python
46-
* ``SciPy`` - scientific libraries for Python
47-
* ``matplotlib`` - python plotting library
64+
Citation
65+
--------
4866

49-
Recommended software:
67+
If you use diffpy.srfit in a scientific publication, we would like you to cite this package as
5068

51-
Optimizations involving crystal structures or molecules require
69+
diffpy.srfit Package, https://github.com/diffpy/diffpy.srfit
5270

53-
* ``diffpy.structure`` - crystal structure container and parsers,
54-
https://github.com/diffpy/diffpy.structure
55-
* ``pyobjcryst`` - Crystal and Molecule storage, rigid units, bond
56-
length and bond angle restraints, https://github.com/diffpy/pyobjcryst
71+
Installation
72+
------------
5773

58-
Optimizations involving pair distribution functions PDF or bond valence
59-
sums require
74+
The preferred method is to use `Miniconda Python
75+
<https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_
76+
and install from the "conda-forge" channel of Conda packages.
6077

61-
* ``diffpy.srreal`` - python library for PDF calculation,
62-
https://github.com/diffpy/diffpy.srreal
78+
To add "conda-forge" to the conda channels, run the following in a terminal. ::
6379

64-
Optimizations involving small angle scattering or shape characteristic
65-
functions from the diffpy.srfit.sas module require
80+
conda config --add channels conda-forge
6681

67-
* ``sas`` - module for calculation of P(R) in small-angle scattering
68-
from the SasView project, http://www.sasview.org
82+
We want to install our packages in a suitable conda environment.
83+
The following creates and activates a new environment named ``diffpy.srfit_env`` ::
6984

70-
We recommend to use `Anaconda Python <https://www.anaconda.com/download>`_
71-
as it allows to install all software dependencies together with
72-
diffpy.srfit. For other Python distributions it is necessary to
73-
install the required software separately. As an example, on Ubuntu
74-
Linux some of the required software can be installed using ::
85+
conda create -n diffpy.srfit_env python=3
86+
conda activate diffpy.srfit_env
7587

76-
sudo apt-get install \
77-
python3-setuptools python3-numpy python3-scipy python3-matplotlib
88+
Then, to fully install ``diffpy.srfit`` in our active environment, run ::
7889

79-
For other required packages see their respective web pages for installation
80-
instructions.
90+
conda install diffpy.srfit
8191

92+
Another option is to use ``pip`` to download and install the latest release from
93+
`Python Package Index <https://pypi.python.org>`_.
94+
To install using ``pip`` into your ``diffpy.srfit_env`` environment, we will also have to install dependencies ::
8295

83-
INSTALLATION
84-
------------------------------------------------------------------------
96+
pip install -r https://raw.githubusercontent.com/diffpy/diffpy.srfit/main/requirements/run.txt
8597

86-
The preferred method is to use Anaconda Python and install from the
87-
"diffpy" channel of Anaconda packages ::
98+
and then install the package ::
8899

89-
conda config --add channels diffpy
90-
conda install diffpy.srfit
100+
pip install diffpy.srfit
91101

92-
diffpy.srfit is also included in the "diffpy-cmi" collection
93-
of packages for structure analysis ::
102+
If you prefer to install from sources, after installing the dependencies, obtain the source archive from
103+
`GitHub <https://github.com/diffpy/diffpy.srfit/>`_. Once installed, ``cd`` into your ``diffpy.srfit`` directory
104+
and run the following ::
94105

95-
conda install diffpy-cmi
106+
pip install .
96107

97-
Another option is to use ``easy_install`` to download and install the
98-
latest release from `Python Package Index <https://pypi.python.org>`_ ::
108+
Support and Contribute
109+
----------------------
99110

100-
easy_install diffpy.srfit
111+
`Diffpy user group <https://groups.google.com/g/diffpy-users>`_ is the discussion forum for general questions and discussions about the use of diffpy.srfit. Please join the diffpy.srfit users community by joining the Google group. The diffpy.srfit project welcomes your expertise and enthusiasm!
101112

102-
If you prefer to install from sources, make sure all required software
103-
packages are in place and then run ::
113+
If you see a bug or want to request a feature, please `report it as an issue <https://github.com/diffpy/diffpy.srfit/issues>`_ and/or `submit a fix as a PR <https://github.com/diffpy/diffpy.srfit/pulls>`_. You can also post it to the `Diffpy user group <https://groups.google.com/g/diffpy-users>`_.
104114

105-
python setup.py install
115+
Feel free to fork the project and contribute. To install diffpy.srfit
116+
in a development mode, with its sources being directly used by Python
117+
rather than copied to a package directory, use the following in the root
118+
directory ::
106119

107-
You may need to use ``sudo`` with system Python so the process is
108-
allowed to put files to the system directories. If administrator (root)
109-
access is not available, consult the output from
110-
``python setup.py install --help`` for options to install to a
111-
user-writable locations. The installation integrity can be verified by
112-
changing to the HOME directory and running ::
120+
pip install -e .
113121

114-
python -m diffpy.srfit.tests.run
122+
To ensure code quality and to prevent accidental commits into the default branch, please set up the use of our pre-commit
123+
hooks.
115124

125+
1. Install pre-commit in your working environment by running ``conda install pre-commit``.
116126

117-
DEVELOPMENT
118-
------------------------------------------------------------------------
127+
2. Initialize pre-commit (one time only) ``pre-commit install``.
119128

120-
diffpy.srfit is an open-source software developed as a part of the DiffPy-CMI
121-
complex modeling initiative at the Brookhaven National Laboratory. The
122-
diffpy.srfit sources are hosted at
123-
https://github.com/diffpy/diffpy.srfit.
129+
Thereafter your code will be linted by black and isort and checked against flake8 before you can commit.
130+
If it fails by black or isort, just rerun and it should pass (black and isort will modify the files so should
131+
pass after they are modified). If the flake8 test fails please see the error messages and fix them manually before
132+
trying to commit again.
124133

125-
Feel free to fork the project and contribute. To install diffpy.srfit
126-
in a development mode, with its sources being directly used by Python
127-
rather than copied to a package directory, use ::
134+
Improvements and fixes are always appreciated.
128135

129-
python setup.py develop --user
136+
Before contribuing, please read our `Code of Conduct <https://github.com/diffpy/diffpy.srfit/blob/main/CODE_OF_CONDUCT.rst>`_.
130137

131138

132-
ACKNOWLEDGEMENT
139+
Acknowledgements
133140
------------------------------------------------------------------------
134141

135142
The source code in *observable.py* was derived from the 1.0 version
136143
of the Caltech "Pyre" project.
137144

145+
Contact
146+
-------
138147

139-
CONTACTS
140-
------------------------------------------------------------------------
141-
142-
For more information on diffpy.srfit please visit the project web-page
143-
144-
http://www.diffpy.org
145-
146-
or email Prof. Simon Billinge at [email protected].
148+
For more information on diffpy.srfit please visit the project `web-page <https://diffpy.github.io/>`_ or email Prof. Simon Billinge at [email protected].

0 commit comments

Comments
 (0)