Reduced units: Add link to user guide section in LJ tutorial

[kosovan]

Reduced units are not explained in the tutorials. The statement in Tutorial 1: Conventionally, reduced units are employed, in other words LJ units. is not informative for a new user.

Proposed solution: explain the reduced units in Tutorial 1 or make a separate tutorial on units.

[kosovan]

I plan to work on this in the near future.

[jonaslandsgesell]

Good idea: Please introduce the concept of unit conversion by inroducing the multiplication with 1.

Example:

1km= 1km 1 = 1km 1000m/km = 1000 m

There is also the possibility to link to https://en.wikipedia.org/wiki/Conversion_of_units#Conversion_factors in jupyter notebooks https://stackoverflow.com/questions/25692293/inserting-a-link-to-a-webpage-in-an-ipython-notebook

[kosovan]

@jonaslandsgesell I was not suggesting that we should teach simple unit conversion. You would normally learn this at the primary school, not from the Espresso tutorial.

Nevertheless, many users have problems with reduced units. What we need to explain is

1. How to choose a suitable system of reduced units that is uniquely defined and internally consistent;
2. How to choose it so that it reflects some characteristic scales of the problem, in order to get a small number of dimensionless parameters uniquely charecterizing your system. This concept is beyond the scope of many graduate courses of Physics and Chemistry, it is related to the law of corresponding states

[jonaslandsgesell]

@kosovan The problem of converting to LJ units is of the same kind: 0.355 Angstrom = 0.355 Angstrom 1 = 0.355 Angstrom (1sigma /0.355 Angstrom) = 1 sigma (given then choice 1sigma = 0.355 Angstrom). One can do any conversion with this scheme and it is straight forward to introduce LJ units like this. The same works with energies and masses... Consistency will drop out automatically in this case (given you only choose a length, energy and mass unit and derive the time unit).

PS: from my experience also converting a simulation result back to SI units poses a problem. I would suggest to add this to the tutorial.

[KaiSzuttor]

i agree with @jonaslandsgesell. We have seen a lot of students struggling with this and the proposed scheme is easy to remember and helps in more complex conversions.

However, I think best practice would be to use a dedicated python package like pint (we should use the advantages of the python ecosystem after we have paid a lot for it).

I use pint myself, .e.g. by putting the following in a separate module, lets call it ureg.py next to the simulation script:

import pint

ureg = pint.UnitRegistry()
ureg.define('md_distance = 4.25 * angstrom')
ureg.define('md_time = 1e-12 * second')
ureg.define('md_energy = 300 * degK * k')
ureg.define('md_mass = md_energy * md_time**2 / md_distance**2')
ureg.define('md_force = md_mass * md_distance / md_time**2')
ureg.define('md_inertia_tensor = md_mass * md_distance**2')

It's then easily possible to define the system in SI units and let pint do the conversions, e.g. :

system = espressomd.System(box_l=box_l.to('md_distance').magnitude)

This is important for an espresso tutorial because it shows best practice with regards to simulation technics. This is something that is not covered by any lectures that I know of.

In the long term we should also think about integrating a dimension-aware python interface.

[KaiSzuttor]

@jonaslandsgesell I was not suggesting that we should teach simple unit conversion. You would normally learn this at the primary school, not from the Espresso tutorial.

Nevertheless, many users have problems with reduced units. What we need to explain is

1. How to choose a suitable system of reduced units that is uniquely defined and internally consistent;
2. How to choose it so that it reflects some characteristic scales of the problem, in order to get a small number of dimensionless parameters uniquely charecterizing your system. This concept is beyond the scope of many graduate courses of Physics and Chemistry, it is related to the law of corresponding states

i think that we do not want to teach people theoretical physics or concepts but rather how espresso relates to knowledge from physics lectures and known algorithms.

[kosovan]

@KaiSzuttor I disagree. If you teach only the tools without explaining the concepts, this is wrong. It is not a problem to refer to other sources for more detailed explanation of advanced concepts, if such links are readily available. However, I think it is pointless to refer to an article which explains how to convert cm to km.

If the example is shown after explanation of the general concepts, then I think it is OK. However, If you show only an example of how to set up a unit system preferred by @jonaslandsgesell or @kosovan without explaining the general concepts, then it does not convey the key message that you are free to choose your unit system in Espresso.

I believe there was an agreement some time ago that there should be a separate tutorial on using reduced units because this is a persistent problem of many users.

My recent experience is that the LJ tutorial is understandable for a person who has had previous experience with some other simulation software but novice users are lost in the concepts after first few lines. It is because the tutorial explains HOW to do certain things but not WHY. This observation was reproduced with about 10 students and postdocs in my group.

Also, I think that there is a discrepancy between the expected knowledge of the reader. For example, the LJ tutorialexplains some simple concepts, like what is the LJ potential, while it assumes that the reader already knows what are the reduced units typically used for simulating LJ systems. In my opinion, if the reader knows reduced units, then most likely he knows the LJ potential, not vice versa.

[kosovan]

@KaiSzuttor Nevertheless, I agree with this one:

However, I think best practice would be to use a dedicated python package like pint (we should use the advantages of the python ecosystem after we have paid a lot for it).

I use pint myself, .e.g. by putting the following in a separate module, lets call it ureg.py next to the simulation script:

I think that we should show an example of how to use pint for setting up the unit system, after explaining the concept of reduced units, or providing a link to such an explanation. I plan to work on that in the coming weeks.

In the long term we should also think about integrating a dimension-aware python interface. I am not sure if the following is a good idea because there are many good reasons to work with a system of reduced units.

[KaiSzuttor]

@KaiSzuttor I disagree. If you teach only the tools without explaining the concepts, this is wrong. It is not a problem to refer to other sources for more detailed explanation of advanced concepts, if such links are readily available. However, I think it is pointless to refer to an article which explains how to convert cm to km.

Okay, think we should have a general discussion about what we want to cover in tutorials and what we expect as textbook knowledge or knowledge that should be covered by lectures. In general I see your point that it is handy to have the minimal knowledge that is needed to understand the tutorial packaged with the tutorial. However, that might also lead to bloated tutorials and the false impression of the tutorials covering everything there is to know about that specific matter.

[kosovan]

Okay, think we should have a general discussion about what we want to cover in tutorials and what we expect as textbook knowledge or knowledge that should be covered by lectures. In general I see your point that it is handy to have the minimal knowledge that is needed to understand the tutorial packaged with the tutorial. However, that might also lead to bloated tutorials and the false impression of the tutorials covering everything there is to know about that specific matter.

I agree that the tutorial should not become a substitute for a course in computer simulations or statistical mechanics. Defining what is the expected prior knowledge might help making the tutorials internally consistent. I mean, if we expect that the reader does not know topic A, then we should not expected him to know A' and A''.

I am now working with my new students to teach them Espresso and as a by-product of this, I am discovering various inconsistencies in the expected prior knowledge. I will be posting issues when I discover such inconsistencies, and I plan resolve them soon.

[KaiSzuttor]

sounds like a plan 👍 i'm in favour of keeping the tutorials short and stick to 'how can you do what you have learned in your simulation course with espresso'. That way people are not overwhelmed by too much information and can concentrate on the technicalities. But of course we should include the respective context, maybe as a short abstract-like introduction to each tutorial with relevant textbook publication citations.

[KaiSzuttor]

I agree that the tutorial should not become a substitute for a course in computer simulations or statistical mechanics. Defining what is the expected prior knowledge might help making the tutorials internally consistent. I mean, if we expect that the reader does not know topic A, then we should not expected him to know A' and A''.

Concerning the reduced unit system: i expect users of software that is designed to be used for coarse-grained simulations to know what coarse-graining is and therefore how length and time scales are mapped from all-atom (SI units) to coarse-grained (reduced units). A little exaggerated: would you teach users of COMSOL concepts of FEM?

[RudolfWeeber]

IIRC, there is an extensive section on reduced units in the user's guide. So, we could write in tutorial one that

• there are many choices for units
• a common choice in soft matter simulations is to use the thermal energy, the particle diameter and the particle mass as units.
• Refer to the section in the UG for more.

[kosovan]

Concerning the reduced unit system: i expect users of software that is designed to be used for coarse-grained simulations to know what coarse-graining is and therefore how length and time scales are mapped from all-atom (SI units) to coarse-grained (reduced units). A little exaggerated: would you teach users of COMSOL concepts of FEM?

I would definitely consider a detailed explanation of those concepts that are known to be problematic for users.

I was not aware that the reduced units were explained in the user guide. I checked it and I like the explanation. I think that a link to the user guide would solve this particular problem, as proposed by @RudolfWeeber

[jngrad]

offline discussion: Espresso meeting 2021-02-02