Added README to Material_Properties

[TristanHehnen]

Hi,

I've changed the file structure in the Material_Properties directory to reflect the structure of the Calibration_Data directory. I've also added README skeletons for all institutes and provided proper README files for our parameter sets.

This continues PR #160

Best,
Tristan

[TristanHehnen]

I noticed that I had prepared already a README for MaCFP-2 in 2021, however this file was not available on git. I'm not sure if I forgot to send it or if there was an issue with uploading. Could you please check if the other institutes had submitted the respective README files and they got lost somewhere?

[leventon]

Thank you, Tristan. We did not define a specific format / needs for description of model parameterization. Our MaCFP-2 Guidelines simply requested: "2) A description (written and corresponding governing equations) of the participant’s proposed reaction mechanism as well as the method of determination of associated kinetic parameters and material properties. [INSITUTE_ModelDescription.txt OR .docx]

Morgan @mcb1 compiled this information for presentation at the workshop, but I do not think we made README files. He may be able to share what they sent, if you're able to and/or interested in reformatting the required information as needed.

I began editing one of your proposed draft README files, then considered making a template on the DB wiki, and ultimately think this needs further consideration before including as is (especially before including multiple copies of a draft README for all participating labs). It appears that most all of the information (property values, calibration technique/tool, experimental dataset used..) that you have in your README is duplicated from the existing .json file. I do not think we should duplicate this information.

Effectively, the README file you've created provides a written description of info already contained in the .json file - I hesitate to ask participants to provide two copies of such similar info.

What might be more valuable to add to the existing .json file would be two general subcategories to "Calibration" section, which currently includes (for each property, or 'scope') 'model', 'method', and data'. Specifically, I suggest, 'calibration target', and 'notes/References'.
'Calibration target' would be something to the effect of (for example, for TGA data) - RMSE of ML or MLR data, onset Temp of decomp, peak MLR, final residue yield.
'Notes' - could leave a flexible space for critical further details that require more flexible description or references to a relevant work with such General Description of the Parameter Estimation Process.

[leventon]

I want to add - I'm not fully against a README and I think that was added here based on discussions in the previous thread so thank you for that first attempt here but, as is, the current text repeats too much information from the .json file and (especially at pages long) is a lot to ask all participants to repeat/resubmit.
A README providing a simple, "General Description of the Parameter Estimation Process" that, in a paragraph or so, provides a clear, succint overview (e.g., 'xyz parameters were fit/calibrated to this or that data; process was performed in this order...') while details remain in only the .json file (more serachable but still human readable; no repeated info/effort) might be more effective.

[mcb1]

I agree with Isaac. Both "Target" and "Notes" seem like reasonable additional parameters. I don't actually think that "Notes" will be used that much, but it might be a simple stop-gap measure to allow for some important details to be stored at the discretion of the submitter.

All labs submitted some form of document describing their results. Since we didn't give them very precise instructions, the level of detail provided (and file format) was highly variable. So it looks like our options are to either (a) try to tidy up the JSON files, (b) ask the contributors to submit README files according to some proposed format, or (c) one (or several) of us can go through and create README files from the documents they submitted. I think option (b) would be too much to ask and rather impolite at this point. So the question is whether or not it is worthwhile to put in the work to execute option (c).

I'll try to go through the current JSON files and add the "Target" and "Note" fields as best I can from the submissions I received. We can then request that the contributors check their JSON files. If everyone is happy with the results then I think we can forego creating README files.