diff --git a/docs/FAQ.rst b/docs/FAQ.rst index b9922f7b..bfc0093c 100644 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -3,7 +3,7 @@ FAQ ================= -1. Precission Loss +1. Precision Loss ^^^^^^^^^^^^^^^^^^ :: @@ -12,9 +12,9 @@ FAQ Check the jac value, -1.1 If all absulute value is small. it is acceptable beacuse of the precision. +1.1 If all absulute values are small. it is acceptable because of the precision. -1.2 If some absulte value is large. It is the bad parameters or problem in models. +1.2 If some absolute values are large. It is due to the bad parameters or some problem in the models. 1.3 Avoid negative weights @@ -28,34 +28,34 @@ Check the jac value, 2.1 Check the data. ------------------- -There a script (scripts/check_nan.py) to check it. +There is a script (scripts/check_nan.py) to check it. -2.1.1 No stange value in data, (nan, infs ...). +2.1.1 No strange value in data, (nan, infs ...). 2.1.2 The data order should be :math:`E, p_x, p_y,p_z`, :math:`E` is the first. -2.1.3 The mass should be valid, :math:`E^2 - p_x^2 - p_y^2 - p_z^2 > 0`, and for any combinations of final particles, mab > ma + mb. +2.1.3 The mass should be valid, :math:`E^2 - p_x^2 - p_y^2 - p_z^2 > 0`, and for any combination of final particles, mab > ma + mb. -2.1.4 Avoid 0 in weights. +2.1.4 Avoid including 0 in the weights. 2.2 Check the model. -------------------- -2.2.1 The resonaces mass should be valid, for example in the mass range (m1+m2, m0-m3), out of the threshold required special options. +2.2.1 The resonances mass should be valid, for example in the mass range (m1+m2, m0-m3), out of the threshold required for special options. 3. NaN value when getting params error. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - numpy.linalg.LinAlgError: Array must not contain infs or NaN. + numpy.linalg.LinAlgError: Arrays must not contain infs or NaN. 3.1 Similar as sec 2.2. -3.2 Bad fit parameters: too wide width or two narrow width, reach the boundary and so on. +3.2 Bad fit parameters: width too narrow or wide, reach the boundary and so on. -3.3 Bad gradients. No gradients or the gradients is not corret for fit paramters. +3.3 Bad gradients. No gradients or the gradients are not correct for fit paramters. 4. Singular Matrix when getting params error ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -64,9 +64,9 @@ There a script (scripts/check_nan.py) to check it. numpy.linalg.LinAlgError: Singular matrix -4.1 Free paramters are not used in model. +4.1 Free parameters are not used in the model. -4.2 Used numpy for calculation of variable. The calculation have to be done in get_amp with TensorFlow. +4.2 Used numpy for calculation of variable. The calculations have to be done in get_amp with TensorFlow. .. code:: @@ -74,7 +74,7 @@ There a script (scripts/check_nan.py) to check it. def init_params(self): self.a = self.add_var("a") def get_amp(self, data, *args, **kwargs): - # avoid use numpy for varible as + # avoid using numpy for variable as a = np.sin(self.a()) # use tensorflow instead a = tf.sin(self.a()) @@ -100,9 +100,9 @@ There a script (scripts/check_nan.py) to check it. data: lazy_call: True -5.1.3 Try to use small data sample, or simple cases (less final particles). +5.1.3 Try to use a small data sample, or simpler cases (less final particles). -5.1.4 Some speical model required large memory (such as interpolation model), try other model. +5.1.4 Some special models require large memory (such as an interpolation model), try another model. 5.2 CPU ------------------- @@ -134,7 +134,7 @@ Check the yaml file (see https://yaml.org): the indent, speical chars :code:`,:} AssertionError: not only one top particle -The decay chain should be complete. All the item in decay should decay from initial to finals. +The decay chain should be complete. All the item in decay chain should decay from initial to final state. 6.3 Decay chain 2 @@ -142,10 +142,10 @@ The decay chain should be complete. All the item in decay should decay from init :: - RuntimeError: not decay chain aviable, check you config.yml + RuntimeError: not decay chain available, check your config.yml 6.3.1 Similar as sec 6.2. -6.3.2 Check the information in *remove decay chain*, see the reson why those decays are not aviable. +6.3.2 Check the information in *remove decay chain*, see the reason why those decays are not available. -*ls not aviable* means no possible LS combination allowed. Check the spin and parity. If allow parity voilate, add :code:`p_break: True` to decay. +*ls not available* means no possible LS combination allowed. Check the spin and parity. If parity is allowed to be violated, add :code:`p_break: True` to decay. diff --git a/docs/amplitude.rst b/docs/amplitude.rst index 66dfd3d5..26f40c7a 100644 --- a/docs/amplitude.rst +++ b/docs/amplitude.rst @@ -6,7 +6,7 @@ Amplitude Helicity Formula ________________ -Each Decay has Amplitude like +Each Decay has Amplitude defined like: .. math:: A^{A \rightarrow B+C}_{\lambda_{A},\lambda_{B},\lambda_{C}} = H_{\lambda_{B},\lambda_{C}}^{A \rightarrow B+C} D^{J_{A}\star}_{\lambda_{A},\lambda_{B}-\lambda_{C}}(\phi,\theta,0) diff --git a/docs/custom_model.rst b/docs/custom_model.rst index 9356ee93..de8d9a7b 100644 --- a/docs/custom_model.rst +++ b/docs/custom_model.rst @@ -57,7 +57,7 @@ We can also add parameters in the `.Model` ``init_params`` using ``self.add_var( return tf.complex( m + self.a(), zeros) Then a parameters ``{particle_name}_a`` will appear in the parameters, we use ``self.a()`` to get the value in ``get_amp``. -Note, the type of return value should be ``tf.complex``. All builtin model is located in ``tf_pwa/amp.py``. +Note, the type of return value should be ``tf.complex``. All built in models are located in ``tf_pwa/amp.py``. @@ -75,9 +75,9 @@ There is a simple method to define Resonance model, like def r_line(m, a: FloatParams = 1.0): return m + a -Those code will build a class similar as Line model define before. +Those code will build a class similar as Line model defined before. By using `inspect` module, we can get the `FullArgSpec` of a function. -For a keyword arguments with type annotation as `FloatParams`, it will be treated as a fit paraments. +For a keyword arguments with type annotation as `FloatParams`, it will be treated as a fit parameter. .. note:: the first arguments have to be the invariant mass `m` of the resonance. diff --git a/docs/decay_topology.rst b/docs/decay_topology.rst index 3e1a3a87..d807b541 100644 --- a/docs/decay_topology.rst +++ b/docs/decay_topology.rst @@ -59,5 +59,5 @@ there are the three possible decay chains of A -> B,C,D :: the process is unique for different final particles -Each inserting process delete a line and add three new line, +Each process inserted, deletes a line and adds three new lines. So for decay process has :math:`n` final particles, there are :math:`(2n-3)!!` possible decay topology. diff --git a/docs/developer.rst b/docs/developer.rst index 9a1cac79..39f7f281 100644 --- a/docs/developer.rst +++ b/docs/developer.rst @@ -1,21 +1,19 @@ -Setup for Developer Enveriment ------------------------------- +Setup for Developer Environment +------------------------------- .. note:: - Before the developing, creating a standalone enveriment is recommanded (see https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands for more). + Before developing, creating a standalone environment is recommended (see https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands for more). +The main steps are similar to the normal installation process; however, two additional steps are to be performed here. -The main steps are similar as normal install, only two extra things need to be done. - -The first things is writing tests, and tests your code. -We use pytest (https://docs.pytest.org/en/stable/) framework, You should install it. +The first thing is writing tests and then testing your code. +We use pytest (https://docs.pytest.org/en/stable/) framework for the same, it should be installed as well. .. code:: conda install pytest pytest-cov pytest-benchmark - -The other things is `pre-commit`. it need for developing. +The other thing is `pre-commit`. It is needed for development. 1. You can install `pre-commit` as @@ -29,24 +27,24 @@ and .. code:: - conda install pylint # local dependences + conda install pylint # local dependencies pre-commit install -You can check if pre-commit is working well by running +You can check if pre-commit is working well by running: .. code:: pre-commit run -a -It may take some time to install required package. +It may take some time to install required packages. .. note:: If there are some `GLIBC_XXX` errors at this step, you can try to install `node.js`. .. note:: - For developer using editor with formatter, you should be careful for the options. + For developers using an editor with a formatter, you should be careful about the options. -The following are all commands needed +The following are all commands needed: .. code:: diff --git a/docs/index.rst b/docs/index.rst index d19824cb..6078f651 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,7 +20,7 @@ A detailed configuration file sample (with all usable parameters) can be found * amplitude custom_model decay_topology - resonacnes_params + resonances_params phasespace resolution auto_examples/index @@ -66,7 +66,7 @@ and then fit the data. Fitting is the major part of an analysis, and it could also be the most time-consuming part. For this example (the complexity of the amplitude expression matters a lot), the time for fitting is about xxx (running on xxxGPU). -Then we can step further to complete the analysis, like calculating the fit fractions. +Then we can go one step ahead to complete the analysis, and calculate the fit fractions. .. code-block:: python diff --git a/docs/install.rst b/docs/install.rst index b62d1774..4d1cdc2c 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -4,7 +4,7 @@ Install To use TFPWA, we need some dependent packages. There are two main ways, `conda` and `virtualenv` you can choose *one* of them. *Or* you can choose other method in :ref:`other-method` -1. vitrual environment +1. virtual environment ---------------------- To avoid conflict of dependence, we recommed to use vitrual environment. there are two main vitrual environment for python packages, @@ -62,9 +62,9 @@ and then you can install packages in the conda environment .. code:: - source ./tfpwa/bin/activete + source ./tfpwa/bin/activate -- 1.2.5 You can exit the environment by +- 1.2.5 You can exit the environment by .. code:: @@ -104,10 +104,10 @@ When using `virtualenv`, there is also simple way to install tensorflow2 You can use `-i https://pypi.tuna.tsinghua.edu.cn/simple` option to use pypi mirror site. -3. Other dependences --------------------- +3. Other dependencies +--------------------- -Other dependences of TFPWA is simple. +Other dependencies of TFPWA is simple. 3.1 Get TFPWA package @@ -124,16 +124,16 @@ Get the packages using 3.2 conda ````````` -3.2.1 other dependences +3.2.1 other dependencies -In conda environment, go into the directory of `tf-pwa`, you can install the rest dependences by +In conda environment, go into the directory of `tf-pwa`, you can install rest of the dependencies by .. code:: conda install --file requirements-min.txt .. note:: - we recommed Ampere card users to install with + we recommend Ampere card users to install with `tensorflow_2_6_requirements.txt` (see this `technical FAQ `_). @@ -156,7 +156,7 @@ Using `-e`, so it can be updated by `git pull` directly. 3.3 virtualenv `````````````` -In virtualenv, You can install dependences and TFPWA together. +In virtualenv, You can install dependencies and TFPWA together. .. code:: @@ -165,10 +165,10 @@ In virtualenv, You can install dependences and TFPWA together. Using `-e`, so it can be updated by `git pull` directly. -4. (option) Other dependences. -------------------------------- +4. (option) Other dependencies. +-------------------------------- - There are some option packages, such as `uproot` for reading root file. + There are some optional packages, such as `uproot` for reading root file. 4.1 conda ````````` @@ -200,7 +200,7 @@ We also provided other install method. 5.1 conda channel (experimental) ```````````````````````````````` -A pre-built conda package (Linux only) is also provided, just run following +A pre-built conda package (Linux only) is also provided, just run the following command to install it. .. code:: @@ -209,7 +209,7 @@ command to install it. conda install tf-pwa 5.2 pip -```````` +`````````` When using `pip`, you will need to install CUDA to use GPU. Just run the following command : diff --git a/docs/phasespace.rst b/docs/phasespace.rst index f8c8190e..170fcbbb 100644 --- a/docs/phasespace.rst +++ b/docs/phasespace.rst @@ -19,7 +19,7 @@ by using the property of :math:`\delta`-function, where :math:`x_i` is the root of :math:`f(x)=0`. -Phase space has the follow chain rule, +Phase space has the following chain rule, .. math:: \mathrm{d} \Phi(P;p_1,\cdots,p_n) =& (2\pi)^4\delta^4(P - \sum {p_i}) \prod \frac{1}{2E_i}\frac{\mathrm{d}^3 \vec{p_i}}{(2\pi)^{3}} \\ @@ -48,14 +48,14 @@ where :math:`\mathrm{d} \Omega = \mathrm{d}(\cos\theta)\mathrm{d}\varphi` and |\vec{p}| = \frac{\sqrt{(M^2 - (m_1 + m_2)^2)(M^2 -(m_1 - m_2)^2)}}{2M} -The three body decay in the center mass frame :math:`P=(M,0,0,0),q^\star=(m_{23},0,0,0)`, +The three body decay in the center of mass frame :math:`P=(M,0,0,0),q^\star=(m_{23},0,0,0)`, .. math:: \mathrm{d} \Phi(P;p_1,p_2,p_3) =& \mathrm{d}\Phi(P;p_1,q) \mathrm{d}\Phi(q^\star;p_2^\star,p_3^\star) \frac{\mathrm{d} q^2}{2\pi} \\ =& \frac{|\vec{p_1}||\vec{p_2^\star}|}{(2\pi)^5 16 M m_{23}} \mathrm{d} m_{23}^2 \mathrm{d} \Omega_1 \mathrm{d}\Omega_2^\star \\ =& \frac{|\vec{p_1}||\vec{p_2^\star}|}{(2\pi)^5 8 M} \mathrm{d} m_{23} \mathrm{d} \Omega_1 \mathrm{d}\Omega_2^\star -The n body decay in the center mass frame :math:`P=(M,0,0,0)`, +The N body decay in the center of mass frame :math:`P=(M,0,0,0)`, .. math:: \mathrm{d} \Phi(P;p_1,\cdots,p_n) =& \mathrm{d}\Phi(P;p_1,q_1)\prod_{i=1}^{n-2} \frac{\mathrm{d} q_{i}^2}{2\pi}\mathrm{d}\Phi(q_{i},p_{i+1},p_{i+2})\\ @@ -75,7 +75,7 @@ with those limit Phase Space Generator --------------------- -For n body phase space +For N body phase space .. math:: \mathrm{d} \Phi(P;p_1,\cdots,p_n) = diff --git a/docs/resolution.rst b/docs/resolution.rst index 5ff070c9..6296f1f8 100644 --- a/docs/resolution.rst +++ b/docs/resolution.rst @@ -1,7 +1,7 @@ Resolution in Partial Wave Analysis ----------------------------------- -Resolution is the effect of detector. To Consider the resolution properly, We need to take a general look about the detector process. We can divide the process of detector into two parts. +Resolution is the effect of the detector. To consider the resolution properly, We need to take a general look at the detector process. We can divide the process of the detector into two parts. The first part is acceptance, with the probability for truth value :math:`x` as :math:`\epsilon_{T} (x)`. The second part is resolution, it means the measurement value :math:`y` will be a random number base on truth value :math:`x`. It is a conditional probability as :math:`R_{T}(y|x)`. The conditional probability is normalized as :math:`\int R_{T}(y|x) \mathrm{d} y = 1`. So, the total effect of detector is transition function @@ -9,7 +9,7 @@ So, the total effect of detector is transition function .. math:: T(x,y) = R_{T}(y|x)\epsilon_{T} (x). -When we have a distribution of truth value with probability :math:`p(x)`, then we can get the distribution of measurement value with probability +When we have a distribution of the true value with probability :math:`p(x)`, then we can get the distribution of measured value with probability .. math:: p'(y)= \int p(x) T(x,y) \mathrm{d} x. @@ -44,20 +44,20 @@ The final negative log-likelihood with considering resolution is .. math:: - \ln L = -\sum \ln \frac{p'(y)}{\int p'(y) \mathrm{d}y} = -\sum \ln \frac{\int p(x) R(x|y) \mathrm{d} x}{ \int p(x) \epsilon_{T} (x) \mathrm{d} x } - \sum \ln \epsilon_{R}(y). -The last part is a constant, we can ignore it in fit. In the numerical form, it can be written as +The last part is a constant, we can ignore it in the fit. In the numerical form, it can be written as .. math:: - \ln L = -\sum \ln \frac{1}{M}\sum_{x \sim R(x|y)} p(x) + N \ln \sum_{x \sim \epsilon_{T}(x)} p(x). -For the second part, which we already have MC sample with :math:`x \sim \epsilon_{T}(x)`, we can use MC sample to do the sum directly. +For the second part, which we already have MC sample with :math:`x \sim \epsilon_{T}(x)`, we can use the MC sample to do the sum directly. For the first part, we can generate some :math:`x` (:math:`M` times) for every :math:`y` (:math:`N` events). Using the generated samples (:math:`MN` events), we can calculate though the summation. -In addition, we can insert some importance information for the summation as +In addition, we can insert some important information for the summation as .. math:: \int p(x) R(x|y) \mathrm{d} x \approx \frac{1}{\sum w_i} \sum_{x\sim \frac{R(x|y)}{w_i(x)}} w_i p(x). -We need to keep the normalization. For example, we can use Gauss-Hermite quadrature. +We need to keep the normalization. For example, we can use the Gauss-Hermite quadrature. In a simple situation, we only use mass for the variable for resolution function. We can build the datasets by replacing the mass by random number based on the resolution function, diff --git a/docs/resonacnes_params.rst b/docs/resonances_params.rst similarity index 90% rename from docs/resonacnes_params.rst rename to docs/resonances_params.rst index f8a3fe72..0bc9548d 100644 --- a/docs/resonacnes_params.rst +++ b/docs/resonances_params.rst @@ -36,11 +36,11 @@ From `Resonacces.yml` to the real model, there will be following steps. The particle class is `cls = get_particle_model(item["model"])`, and the object is `cls(**item)`. - All parameters wull be stored in `config.particle_property[name]`. + All parameters will be stored in `config.particle_property[name]`. -All aviable parameters can be devied into the flowowing 3 sets. +All available parameters can be divided into the following 3 sets. Common Parameters ----------------- @@ -71,10 +71,10 @@ Model Parameters Parameters defined in the real model. :doc:`particle_model` -There are many parameters defined by the user, the those parameters will be pass to model class, +There are many parameters defined by the user, then those parameters will be passed to the model class, such as the paramthers for `__init__(self, **kwargs)` method. -For examples, the default model (`BWR`, `~tf_pwa.particle.BaseParticle`) have following parameters: +For example, the default model (`BWR`, `~tf_pwa.particle.BaseParticle`) has the following parameters: +---------------------+-----------------------------+----------------------------------------+ | name | default value | comment | @@ -90,7 +90,7 @@ Other Parameters There are also some other parameters which is used to control the program running. -For examples, simple constrains, the following parameters are using by `~tf_pwa.config_loader.ConfigLoader` as constrains. +For example, simple constraints, the following parameters are used by `~tf_pwa.config_loader.ConfigLoader` as constraints. +----------------------------+----------------+-----------------------------------+ | name | default value | comment | @@ -103,7 +103,7 @@ For examples, simple constrains, the following parameters are using by `~tf_pwa. +----------------------------+----------------+-----------------------------------+ -Another examples are parameters to build decay chain for particle `R`. +Another example are parameters to build decay chain for particle `R`. +------------------------+----------------+----------------------------------------------------------+ | name | default value | comment | @@ -115,7 +115,7 @@ Another examples are parameters to build decay chain for particle `R`. | `model` | `default` | Particle model for `R` | +------------------------+----------------+----------------------------------------------------------+ -There are also other common used parameters. +There are also other commonly used parameters. +------------------------+----------------+----------------------------------------------------------+ | name | default value | comment | diff --git a/docs/tensorflow_version.rst b/docs/tensorflow_version.rst index 99b0d162..b088dc74 100644 --- a/docs/tensorflow_version.rst +++ b/docs/tensorflow_version.rst @@ -14,4 +14,4 @@ Tensorflow and Cudatoolkit Version 4. **Will you update the** `tensorflow_2_X_requirements.txt` **file regularly to the latest available version on `conda`?** - We do not guarantee any regular updates on `tensorflow_2_X_requirements.txt`. - - We will update this should particular build become unavailable on `conda` **or** a new release of GPUs require a `tensorflow` and `cudatoolkit` update. Please notify us if this is the case. + - We will update this should a particular build becomes unavailable on `conda` **or** a new release of GPUs require a `tensorflow` and `cudatoolkit` update. Please notify us if this is the case.