diff --git a/build/README.md b/build/README.md index a873c7d103077d8dbc81dea056f79cccf5349d10..0d13383aacd592ba4d48ad5f4fe2062be0143577 100644 --- a/build/README.md +++ b/build/README.md @@ -4,34 +4,44 @@ This directory collects all the output of make builds. ## Instructions -The original code produces output in the current working directory (the path where the code is executed from). The build directory is intended to collect local builds and test run output in a safe place, without cluttering the code development folders, thus helping git to filter out unnecessary logs through .gitignore. +The original code produces output in the current working directory (the path where the code is executed from). The build directory is intended to collect local builds and test run output in a safe place, without cluttering the code development folders, thus helping `git` to filter out unnecessary logs through `.gitignore`. ## Code work-flow -This section describes the use of the pre-existing programs, once the binaries have been properly built by a succesful run of make in the src folder. +This section describes the use of the pre-existing programs, once the binaries have been properly built by a succesful run of `make` in the `src` folder. ### cluster -1. cd to the build/cluster folder -2. run edfb (./edfb) -3. run clu (./clu) +1. cd to the `build/cluster` folder +2. run `edfb` + + > ./edfb + +3. run `clu` + + > ./clu + +*NOTE:* both `edfb` and `clu` expect an input which is assumed to be in a folder named `../../test_data/cluster/` (i.e. two levels above the current execution path) -NOTE: both edfb and sph expect an input which is assumed to be in a folder named "../../test_data/cluster/" (i.e. two levels above the current execution path) - -TODO: set up a code variable to locate the input data (data file paths should not be hard-coded) +*TODO:* set up a code variable to locate the input data (data file paths should not be hard-coded) ### sphere -1. cd to the build/sphere folder -2. run edfb (./edfb) -3. run sph (./sph) +1. cd to the `build/sphere` folder +2. run `edfb` + + > ./edfb + +3. run `sph` -NOTE: both edfb and sph expect an input which is assumed to be in a folder named "../../test_data/sphere/" (i.e. two levels above the current execution path) + > ./sph + +*NOTE:* both `edfb` and `sph` expect an input which is assumed to be in a folder named `../../test_data/sphere/` (i.e. two levels above the current execution path) -TODO: set up a code variable to locate the input data (data file paths should not be hard-coded) +*TODO:* set up a code variable to locate the input data (data file paths should not be hard-coded) ### trapping The execution of trapping programs requires at least one of the previous programs to have produced a complete output set. -TODO: investigate which conditions allow clu or sph to write TTMS output files. \ No newline at end of file +*TODO:* investigate which conditions allow `clu` or `sph` to write `TTMS` output files. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000000000000000000000000000000000000..29f340e1f259c9566529d369e6e9dc3923058a8d --- /dev/null +++ b/src/README.md @@ -0,0 +1,9 @@ +# Folder instructions + +This directory collects the source code of the original programs and the development folders. + +## Instructions + +The original code is contained in the folders named `cluster`, `sphere` and `trapping`. Each folder contains a `Makefile` to compile either the whole program set or the single programs. A global `Makefile`, which contains instructions to build all the original source code, is available directly in the `src` folder. + +In all cases, build commands executed through `make` will output the object files and the linked binaries in the proper folders under the build directory. diff --git a/test_data/README.md b/test_data/README.md index 77cffcf6ab6d8abcae441501636c6484faa65d1c..d6f22fda2e0e95ded0d0389f13d4aa6566d1cf5b 100644 --- a/test_data/README.md +++ b/test_data/README.md @@ -1 +1,34 @@ -This directory collects the input files for test the code. +# Folder instructions + +This directory collects the input files to test the code. + +## Instructions + +The execution of the original code can be controlled through a set of configuration files that define the characteristics of the problem and affect the type of output. The following sections describe the contents of the configuration files and, to some extent, thos of the output ones, presenting one code in each section. + +### cluster + +cluster is designed to calculate a complex geometry made up by many spheres. These can be either fully embedded in a larger sphere or separated within the external medium. Sphere compenetration is not accounted for. + +*TODO:* add the description of the cluster configuration files + +### sphere + +sphere is designed to perform the simplest case calculation, namely the scattering of incident radiation on a single sphere. To perform the calculation, the two following formatted files need to be provided: + +*TODO:* write the the DEDFB documentation + +- DSPH +``` + SPHERE_NUMBER MAXIMUM_L_ORDER POLARIZATION_STATUS TRANSITION_SHARPNESS_1 TRANSITION_SHARPNESS_2 GEOMETRY + STARTING_INC_THETA INC_THETA_STEP FINAL_INC_THETA STARTING_SCA_THETA SCA_THETA_STEP FINAL_SCA_THETA + STARTING_INC_PHI INC_PHI_STEP FINAL_INC_PHI STARTING_SCA_PHI SCA_PHI_STEP FINAL_SCA_PHI + WRITE_INTERMEDIATE_FILE +EOF_CODE +``` +were the different lines have the following roles: +1. general configuration of the scattering problem, with some specification of the transition between materials +2. definition of the elevation angle arrays for the incident and scattered radiation fields +3. definition of the azimuth angle arrays for the incident and scattered radiation fields +4. a flag to set whether the intermediate data should be written to output files +5. an end-of-file code (generally 0)