expand README

README.md

@@ -1,3 +1,120 @@
 # RWSims
 
-Collection of rw sim scripts
+Collection of rw sim scripts
+
+## Usage 
+
+```python
+# the next lines are only necessary if the python script is not in the same folder as rwsims
+import sys
+sys.path.append('/path/to/RWSims')
+
+from rwsims.sims import run_ste_sim, run_spectrum_sim
+
+run_ste_sim('/path/to/json-file')
+run_spectrum_sim('/path/to/json-file')
+```
+
+## Parameter file
+
+Parameter for a simulation are given by a JSON file, sections are:
+
+### simulation
+
+| key  | type            | description                            |
+|------|-----------------|----------------------------------------|
+| num  | integer         | Number of trajectories                 |
+| seed | integer or null | Seed value for random number generator | 
+
+### molecule
+
+| key   | type  | description        |
+|-------|-------|--------------------|
+| delta | float | Anisotropy (in Hz) |
+| eta   | float | Asymmetry          |
+
+### correlation_times
+
+| key             | type       | description                                                               |
+|-----------------|------------|---------------------------------------------------------------------------|
+| distribution    | string     | Name of distribution. Possible values: `DeltaDistribution`, `LogGaussian` |
+| tau             | _variable_ | Characteristic time of distribution (in s)                                |
+| Other parameter | _variable_ | Additional parameter, e.g., sigma                                         |
+  
+### motion
+
+| key             | type       | description                                                      |
+|-----------------|------------|------------------------------------------------------------------|
+| model           | string     | Name of motion. Possible values: `RandomJump`, `TetrahedralJump` |
+
+
+### spectrum
+
+| key             | type       | description                                       |
+|-----------------|------------|---------------------------------------------------|
+| dwell_time      | float      | Dwell time of acquisition (in s)                  |
+| num_points      | integer    | Number of acquisition points                      |
+| t_echo          | _variable_ | One or more echo delays (use zero for FID) (in s) |
+| line_broadening | float      | Additional exponential broadening (in Hz)         |
+| t_pulse         | float      | Pulse length used of attenuation (in s)           |
+
+### ste
+
+| key             | type       | description                                     |
+|-----------------|------------|-------------------------------------------------|
+| t_evo           | _variable_ | One or more evolution times                     |
+| t_mix           | _variable_ | One or more mixing times                        |
+| t_echo          | float      | Optional echo delay for 4-pulse sequence (in s) |
+
+### _variable_ type
+
+Keys of type _variable_ can be a single value, a list of values, or values between a given start and stop value.
+
+Examples:
+
++ A single value 
+
+```json
+{
+  // Other parameter...
+  "tau": 1e-3,
+  // More parameter..
+}
+```
+
++ A list of predefined values, defined by key `list`
+```json
+{
+  // Other parameter...
+  "tau": {
+    "list": [1e-5, 1e-4, 1e-3, 1e-2]
+  },
+  // More parameter..
+}
+```
+
+++ A list of predefined values, based on start and end value
+```json
+{
+  // Other parameter...
+  "tau": {
+    "start": 1e-6,
+    "stop": 1e0,
+    "steps": 31,
+    "is_log": true  // this parameter is optional, default is false
+  },
+  // More parameter..
+}
+```
+
+## Output
+
+Results are written to text files and png images.
++ For spectrum simulations:
+  1. Each combination of distribution and motion parameter produces files for the dependence of timesignals/spectra on the echo delay.
+  2. The reduction factor vs. correlation time is plotted for all variable together in one png plot
++ For STE simulation:
+  1. Each combination of distribution and motion parameter produces files for the CC/SS decays.
+  2. The dependence on the evolution of the fit parameter is saved and plotted for the various variable combinations 
+
+