Index: sasmodels/models/core_shell_parallelepiped.py
===================================================================
 sasmodels/models/core_shell_parallelepiped.py (revision 5bc6d21cb8000cd9bb3d14f07d5f5de178c9b063)
+++ sasmodels/models/core_shell_parallelepiped.py (revision 96153e4bfa35f23278f5f9bdbe4d891544f8c683)
@@ 4,6 +4,12 @@
Calculates the form factor for a rectangular solid with a coreshell structure.
The thickness and the scattering length density of the shell or
"rim" can be different on each (pair) of faces.
+The thickness and the scattering length density of the shell or "rim" can be
+different on each (pair) of faces. The three dimensions of the core of the
+parallelepiped (strictly here a cuboid) may be given in *any* size order as
+long as the particles are randomly oriented (i.e. take on all possible
+orientations see notes on 2D below). To avoid multiple fit solutions, e
+specially with MonteCarlo fit methods, it may be advisable to restrict their
+ranges. There may be a number of closely similar "best fits", so some trial and
+error, or fixing of some dimensions at expected values, may help.
The form factor is normalized by the particle volume $V$ such that
@@ 18,6 +24,6 @@
pulled out of the form factor term due to the multiple slds in the model.
The core of the solid is defined by the dimensions $A$, $B$, $C$ such that
$A < B < C$.
+The core of the solid is defined by the dimensions $A$, $B$, $C$ here shown
+such that $A < B < C$.
.. figure:: img/parallelepiped_geometry.jpg
@@ 104,12 +110,7 @@
~~~~~~~~~~~~~
If the scale is set equal to the particle volume fraction, $\phi$, the returned
value is the scattered intensity per unit volume, $I(q) = \phi P(q)$. However,
**no interparticle interference effects are included in this calculation.**

There are many parameters in this model. Hold as many fixed as possible with
known values, or you will certainly end up at a solution that is unphysical.
The returned value is in units of cm^1, on absolute scale.
NB: The 2nd virial coefficient of the core_shell_parallelepiped is calculated
@@ 120,8 +121,14 @@
For 2d data the orientation of the particle is required, described using
angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below. For further
details of the calculation and angular dispersions see :ref:`orientation`.
The angle $\Psi$ is the rotational angle around the *long_c* axis. For example,
$\Psi = 0$ when the *short_b* axis is parallel to the *x*axis of the detector.
+angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details
+of the calculation and angular dispersions see :ref:`orientation` .
+
+The angle $\Psi$ is the rotational angle around the $C$ axis.
+For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis
+oriented parallel to the yaxis of the detector with $A$ along the xaxis.
+For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated
+$\theta$ degrees in the $zx$ plane and then $\phi$ degrees around the $z$ axis,
+before doing a final rotation of $\Psi$ degrees around the resulting $C$ axis
+of the particle to obtain the final orientation of the parallelepiped.
.. note:: For 2d, constraints must be applied during fitting to ensure that the
Index: sasmodels/models/parallelepiped.py
===================================================================
 sasmodels/models/parallelepiped.py (revision b343226d68c6e3af776c858761eacbaf49e0dd8f)
+++ sasmodels/models/parallelepiped.py (revision 96153e4bfa35f23278f5f9bdbe4d891544f8c683)
@@ 19,8 +19,10 @@
The three dimensions of the parallelepiped (strictly here a cuboid) may be
given in *any* size order. To avoid multiple fit solutions, especially
with MonteCarlo fit methods, it may be advisable to restrict their ranges.
There may be a number of closely similar "best fits", so some trial and
error, or fixing of some dimensions at expected values, may help.
+given in *any* size order as long as the particles are randomly oriented (i.e.
+take on all possible orientations see notes on 2D below). To avoid multiple fit
+solutions, especially with MonteCarlo fit methods, it may be advisable to
+restrict their ranges. There may be a number of closely similar "best fits", so
+some trial and error, or fixing of some dimensions at expected values, may
+help.
The form factor is normalized by the particle volume and the 1D scattering
@@ 80,13 +82,4 @@
of the calculation and angular dispersions see :ref:`orientation` .
.. Comment by Miguel Gonzalez:
 The following text has been commented because I think there are two
 mistakes. Psi is the rotational angle around C (but I cannot understand
 what it means against the q plane) and psi=0 corresponds to ax and by.

 The angle $\Psi$ is the rotational angle around the $C$ axis against
 the $q$ plane. For example, $\Psi = 0$ when the $B$ axis is parallel
 to the $x$axis of the detector.

The angle $\Psi$ is the rotational angle around the $C$ axis.
For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis
@@ 97,4 +90,9 @@
of the particle to obtain the final orientation of the parallelepiped.
+.. note:: For 2d, constraints must be applied during fitting to ensure that the
+ inequality $A < B < C$ is not violated, and hence the correct definition
+ of angles is preserved. The calculation will not report an error,
+ but the results may be not correct.
+
.. _parallelepipedorientation: