improved comments generated

Author: martinspetlik

mlmc/level_simulation.py

@@ -1,34 +1,37 @@
 import attr
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional, Callable
 from mlmc.quantity.quantity_spec import QuantitySpec
 
 
 @attr.s(auto_attribs=True)
 class LevelSimulation:
     """
-    This class is used to pass simulation data at a given level between a Sampler and a SamplingPool
-    User shouldn't change this class
+    Class for passing simulation configuration and metadata for a given level between
+    a Sampler and a SamplingPool.
+
+    User shouldn't modify this class manually.
     """
+
     config_dict: Dict[Any, Any]
-    # Calculate configuration.
+    # Level-specific simulation configuration dictionary.
 
-    common_files: List[str] = None
-    # List of files in the level workspace to copy/symlink to the sample workspace.
+    common_files: Optional[List[str]] = None
+    # List of files in the level workspace to copy or symlink to the sample workspace.
 
     need_sample_workspace: bool = False
-    # If the simulation needs sample workspace at all.
+    # Whether the simulation requires an individual workspace for each sample.
 
-    task_size: int = 0
-    # Relative size of the simulation at this level.
-    # When using PBS, keep in mind that the pbs job size is the sum of task_sizes, and if this sum is above 1,
-    # the job is scheduled and PBS scheduler manages it
+    task_size: float = 0.0
+    # Relative size (or computational cost) of the simulation task at this level.
+    # When using PBS or SLURM, note that the job size is the sum of task_sizes.
+    # If this sum exceeds 1.0, the job is queued and scheduled by the system.
 
-    ### User shouldn't modify the following attributes ###
-    _calculate: Any = None
-    # Calculate method
+    ### Internal attributes — users should not modify these ###
+    _calculate: Optional[Callable] = None
+    # Calculation method used internally by the sampler.
 
-    _level_id: int = None
-    # Level id is set by mlmc.sampler.Sampler. It is internal variable and user shouldn't change it.
+    _level_id: Optional[int] = None
+    # Level identifier, set automatically by mlmc.sampler.Sampler.
 
-    _result_format: List[QuantitySpec] = None
-    # Simulation result format
+    _result_format: Optional[List[QuantitySpec]] = None
+    # Format specification for simulation results (defined by QuantitySpec instances).