Python config update (#62)

* patch admonish syntax

* first few sections of usage guide with python rename

* notes on design

* point out flexibility in how parameters can be set

* start rewriting sim area

* updates as i'm rereading the sim section

* make sure standalone works

Author: tomeichlersmith

src/developing/Logging.md

@@ -8,9 +8,9 @@ The python class `Process` has the `logger` member that configures how the loggi
 
 Parameter | Description
 ---|---
-`filePath` | path to logging file. No logging to file is done if this is not set.
-`fileLevel` | Logging level (and above) to print to the file
-`termLevel` | Logging level (and above) to print to the terminal
+`file_path` | path to logging file. No logging to file is done if this is not set.
+`file_level` | Logging level (and above) to print to the file
+`term_level` | Logging level (and above) to print to the terminal
 
 Besides these parameters you can set directly, the `logger` also has
 the ability to customize logging levels depending on the name of the logging
@@ -19,7 +19,7 @@ channel (usually the processor's name).
 ### Examples
 to lower the level for everyone
 ```python
-p.logger.termLevel = 0
+p.logger.term_level = 0
 ```
 to debug a specific processor
 ```python

src/developing/compatibility.md

@@ -144,7 +144,7 @@ which uses an older version of ROOT.
 The error you see is with using `XYZTVector` which is not present in the `ROOT::Math` namespace
 without including a couple more headers.
 
-~~~admonish example title="Example Compile Error Message", collapsible=true
+~~~admonish example title="Example Compile Error Message" collapsible=true
 I've removed the other errors generated by the compiler, mainly focused on how the `centroid` function
 is not defined anymore since its return type is not defined.
 ```

src/using/analysis/ana-cfg.py

@@ -1,5 +1,6 @@
 from LDMX.Framework import ldmxcfg
 p = ldmxcfg.Process('ana')
-p.sequence = [ ldmxcfg.Analyzer.from_file('MyAnalyzer.cxx', needs=['Ecal_Event']) ]
-p.inputFiles = [ 'events.root' ]
-p.histogramFile = 'hist.root'
+p.sequence = [ ldmxcfg.processor_from_file('MyAnalyzer.cxx', needs=['SimCore_Event', 'Ecal_Event']) ]
+p.input_files = [ 'events.root' ]
+p.histogram_file = 'hist.root'
+p.pause()

src/using/analysis/analyzer-total-rec-energy.cxx

@@ -13,13 +13,6 @@ class MyAnalyzer : public framework::Analyzer {
 };
 
 void MyAnalyzer::onProcessStart() {
-  /**
-   * In v4.5.1 ldmx-sw and earlier, forgetting `getHistoDirectory()`
-   * led to silently not creating any histograms.
-   * In v4.5.2 ldmx-sw and newer, it can be left out but it does
-   * no harm if left in.
-   */
-  getHistoDirectory();
   histograms_.create(
       "total_ecal_rec_energy",
       "Total ECal Rec Energy [GeV]", 160, 0.0, 16.0

src/using/analysis/gen.py

@@ -1,20 +1,19 @@
 from LDMX.Framework import ldmxcfg
 p = ldmxcfg.Process('test')
 from LDMX.SimCore import simulator as sim
-mySim = sim.simulator( "mySim" )
-mySim.setDetector( 'ldmx-det-v14-8gev', True )
+mySim = sim.Simulator( "mySim" )
+mySim.set_detector( 'ldmx-det-v15-8gev', True )
 from LDMX.SimCore import generators as gen
 mySim.generators = [ gen.single_8gev_e_upstream_tagger() ]
-mySim.beamSpotSmear = [20.,80.,0.]
 mySim.description = 'Basic test Simulation'
 p.sequence = [ mySim ]
 p.run = 1
-p.maxEvents = 10000
-p.outputFiles = [ 'events.root' ]
+p.max_events = 10000
+p.output_files = [ 'events.root' ]
 
-import LDMX.Ecal.EcalGeometry
+import LDMX.Ecal.ecal_geometry
 import LDMX.Ecal.ecal_hardcoded_conditions
-import LDMX.Hcal.HcalGeometry
+import LDMX.Hcal.hcal_geometry
 import LDMX.Ecal.digi as ecal_digi
 
 p.sequence = [

src/using/analysis/ldmx-sw.md

@@ -135,8 +135,15 @@ made within the function definitions.
 Look at the [documentation of the HistogramPool](https://ldmx-software.github.io/ldmx-sw/classframework_1_1HistogramPool.html)
 to see more examples of how to `create` and `fill` histograms.
 
+~~~admonish note title="Missing Histograms" collapsible=true
+If the output histogram file you are writing to does not receive any histograms despite
+you following the above procedure, you are probably working with an older version of
+ldmx-sw. In v4.5.1 ldmx-sw and earlier, you needed to include `getHistoDirectory()`
+at the beginning of your `onProcessStart` function.
+~~~
+
 In order to run this code on the data, we need to compile and run the program.
-The special `from_file` function within the config script handles this in
+The special `processor_from_file` function within the config script handles this in
 most situations for us.
 Below, you'll see that the analyzer is re-compiled into the library while
 `fire` is loading the configuration and then the analyzer is used during event processing.

src/using/config/config-basics.md

@@ -17,27 +17,27 @@ Additional notes:
   python module so that the C++ class name, the module name, and any other parameters can be properly spelled once and used everywhere.
 
 ## Minimal Production Config
-In Production Mode, there won't be a `p.inputFiles` line but there will be a line setting `p.run` to some value.
+In Production Mode, there won't be a `p.input_files` line but there will be a line setting `p.run` to some value.
 
 ```python
 from LDMX.Framework import ldmxcfg
 p = ldmxcfg.Process('mypass')
-p.outputFiles = ['output_events.root']
+p.output_files = ['output_events.root']
 p.run = 1
 p.sequence = [
-  ldmxcfg.Producer('my_producer','some::cpp::MyProducer','Module')
+  ldmxcfg.make_processor('my_producer','some::cpp::MyProducer','Module')
 ]
 ```
 
 ## Minimal Reconstruction Config
-In Reconstruction Mode, there will be a `p.inputFiles` line but since `p.run` will be ignored it is often omitted.
+In Reconstruction Mode, there will be a `p.input_files` line but since `p.run` will be ignored it is often omitted.
 
 ```python
 from LDMX.Framework import ldmxcfg
 p = ldmxcfg.Process('myreco')
-p.inputFiles = ['input_events.root']
-p.outputFiles = ['rereco_input_events.root']
+p.input_files = ['input_events.root']
+p.output_files = ['rereco_input_events.root']
 p.sequence = [
-  ldmxcfg.Producer('my_reco', 'some::cpp::MyReco', 'Module')
+  ldmxcfg.make_processor('my_reco', 'some::cpp::MyReco', 'Module')
 ]
 ```

src/using/config/config-tips.md

@@ -17,7 +17,7 @@ args = parser.parse_args()
 from LDMX.Framework import ldmxcfg
 p = ldmxcfg.Process('example')
 p.run = args.run_number
-p.outputFile = [
+p.output_file = [
   str(args.out_dir / f'my_special_simulation_run_{p.run:04d}.root')
 ]
 
@@ -33,12 +33,12 @@ Python's [pathlib](https://docs.python.org/3/library/pathlib.html) library is he
 
 For example, if `input_dir` is a `pathlib.Path` for an input directory of ROOT files.
 ```python
-p.inputFiles = [ str(f) for f in input_dir.iterdir() if f.suffix == '.root' ]
+p.input_files = [ str(f) for f in input_dir.iterdir() if f.suffix == '.root' ]
 ```
 
 We can also use an input file `input_file` to get an output file name and an output directory `output_dir`
 to place this file in the directory we want.
 ```python
-p.outputFiles = [ str(output_dir / (input_file.stem + '_with_my_analyzer.root')) ]
+p.output_files = [ str(output_dir / (input_file.stem + '_with_my_analyzer.root')) ]
 ```
 ~~~

src/using/config/event-skimming.md

@@ -39,12 +39,12 @@ what the default decision is in the case of no hints or a tie in voting.
 
 ### Listening Rules
 The format of the string representing a listening rule is a bit complicated, so it is best
-to just use the `p.skimConsider` function when defining which processors you wish to "listen"
+to just use the `p.skim_consider` function when defining which processors you wish to "listen"
 to (or "consider") when making a skimming decision. Most commonly, a user just has one processor
 that they want to make the skimming decision and in this case you can just provide the processors
 name.
 ```python
-p.skimConsider(my_processor.instanceName)
+p.skim_consider(my_processor.instanceName)
 ```
 Technically, the listening rules use regular expressions for both the processor name and the
 purpose, so one could get quite fancy about which processors (and purposes) are selected.
@@ -57,15 +57,15 @@ processors at all, the default configuration of the default decision is to keep
 any config changes, we keep all events that are processed. Without changing this,
 you could have a processor that explicity "drops" events and update the config to consider
 this processor in order to run over events and drop the "uninteresting" ones
-(using `p.skimConsider` like above).
+(using `p.skim_consider` like above).
 
 On the other hand, we could set the default decision to drop all the events and instead
 have a processor specifically "keep" events that are interesting. In this case, you would
 want to add the following to your config.
 ```python
-p.skimDefaultIsDrop()
+p.skim_default_is_drop()
 ```
-**along with a `p.skimConsider`** so that something ends up in your output event file.
+**along with a `p.skim_consider`** so that something ends up in your output event file.
 
 ~~~admonish warning title="Another Form of Event Dropping"
 This style of event dropping is geared more towards readout, reconstruction, and analysis

src/using/config/intro.md

@@ -33,7 +33,7 @@ There are two processing modes that `fire` can run in which are defined by the p
 If there are no input data files, then `fire` is in _Production Mode_ while if there are input data files, then
 `fire` is in _Reconstruction Mode_. The names of these two modes originate from how `fire` is used in LDMX research.
 
-[^1]: In this context, an "input data file" is a data file previously produced by `fire`. There can be other types of data that are "input" into `fire` but unless `fire` is actually treating those input files as a reference, `fire` is considered to be in "Production Mode". See the `inputFiles` configuration parameter below.
+[^1]: In this context, an "input data file" is a data file previously produced by `fire`. There can be other types of data that are "input" into `fire` but unless `fire` is actually treating those input files as a reference, `fire` is considered to be in "Production Mode". See the `input_files` configuration parameter below.
 
 ## The Process Object
 
@@ -44,31 +44,44 @@ As an example, the pass name is `practice`, so the line which constructs the Pro
 p = ldmxcfg.Process("practice")
 ```
 
+~~~admonish warning title="Parameter Renames"
+As part of our drive to have better organized Python configuratin modules, we applied common
+Python linting and formatting rules to ldmx-sw. This led to many parameters being changed
+from `camelCase` to `snake_case` marked by the release of v4.6.0 of ldmx-sw.
+
+If you are using a version of ldmx-sw prior to v4.6.0, then you will likely need to change
+any `snake_case` parameter name in this example to `camelCase` although that is not true
+in all cases.
+
+The documentation written here does not necessarily fix this rename in all places.
+Please contribute if you find a place that needs to be updated!
+~~~
+
 Here is a list of some of the most important process options and what they control.
 It is encouraged to browse the python modules themselves for all the details, 
 but you can also call `help(ldmxcfg.Process)` in `python` to see the documentation.
 
-- `passName` (string)
+- `pass_name` (string)
    - **required** Given in the constructor, tag for the process as a whole.
    - For example: `"10MeVSignal"` for a simulation of a 10MeV A'
 - `run` (integer)
   - Unique number identifying the run 
   - For example: `9001`
   - Default is `0`
-- `maxEvents` (integer)
+- `max_events` (integer)
    - Maximum number of events to run for
    - Required for Production Mode (no input files)
    - In Reconstruction Mode, the number of events that are run is the number of events in the input files unless this parameter is positive and less than the input number.
    - For example: `9000`
-- `outputFiles` (list of strings)
+- `output_files` (list of strings)
    - List of files to output events to
    - Required to be exactly one for Production Mode, and either exactly one or exactly the number of input files in Reconstruction Mode.
    - For example: `[ "output.root" ]`
-- `inputFiles` (list of strings)
+- `input_files` (list of strings)
    - List of files to read events in from
    - Required if no output files are given
    - For example: `[ "input.root" ]`
-- `histogramFile` (string)
+- `histogram_file` (string)
    - Name of file to put histograms and ntuples in
    - For example: `"myHistograms.root"`
 - `sequence` (list of event processors)
@@ -79,19 +92,22 @@ but you can also call `help(ldmxcfg.Process)` in `python` to see the documentati
    - List of drop/keep rules to help ldmx-sw know which collections to put into output file(s)
    - Slightly complicated, see the [documentation of EventFile](https://ldmx-software.github.io/ldmx-sw/classframework_1_1EventFile.html)
    - For example: `[ "drop .*SimHits.*" , "keep Ecal.*" ]`
-- `skimDefaultIsKeep` (bool)
+- `skim_default_is_keep` (bool)
    - Should the process keep events unless told to drop by a processor?
    - Default is `True`: events will be kept unless processors use `setStorageHint`.
-   - Use `skimDefaultIsDrop()` or `skimDefaultIsSave()` to modify
-- `skimRules` (list of strings)
+   - Use `skim_default_is_drop()` or `skim_default_is_save()` to modify
+- `skim_rules` (list of strings)
    - List of processors to use to decide whether an event should be stored in the output file (along with the default given above).
-   - Has a very specific format, use `skimConsider( processorName )` to modify
-     - `processorName` is the _instance name_ and not the class name
+   - Has a very specific format, use `skim_consider( processorName )` to modify
+     - `processor_name` is the _instance name_ and not the class name
    - For example, the Ecal veto chooses whether an event should be kept or not depending on a lot of physics stuff. If you only want the events passing the veto to be saved, you would:
 ```python
-p.skimDefaultIsDrop() #process should drop events unless specified otherwise
-p.skimConsider('ecalVeto') #process should listen to storage hints from ecalVeto
+p.skim_default_is_drop() #process should drop events unless specified otherwise
+p.skim_consider('ecalVeto') #process should listen to storage hints from ecalVeto
 ```
-- `logFrequency` (int)
+- `log_frequency` (int)
    - How frequently should the processor tell you what event number it is on?
    - Default is `-1` which is never.
+- `logger.term_level` (int)
+    - how severe messages should be before they are printed to the terminal
+    - default is `2` which is warnings and above, the event number printing is at level `1` (info)