From 97a563da38910587ccdd70aa7cf6d73469b2759d Mon Sep 17 00:00:00 2001 From: Dominik Demuth Date: Sat, 3 Aug 2024 19:04:25 +0200 Subject: [PATCH] expand README --- README.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e5bdce0..1b8d614 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,120 @@ # RWSims -Collection of rw sim scripts \ No newline at end of file +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 + +