.. nmass documentation master file, created by sphinx-quickstart on Thu Oct 21 13:17:01 2010. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Chandra multi-mass model tools =================================== This suite of tools provides the tools to derive, use and maintain Chandra multi-mass (aka nmass) models. The key tools and files are: - ``nmass.py``: Actual multi-mass model evaluation code - ``fit_nmass.py``: Calibrate a full multi-mass model - ``nmass_model.py``: Module providing infrastucture for fitting multi-mass model - ``predict_nmass.py``: Predict temperatures for a multi-mass model - ``fit_node.py``: Fit for one node of a multi-mass model using telemetry for coupled nodes - ``node_model.py``: Module providing infrastucture for fitting one node of a multi-mass model - ``predict_node.py``: Predict temperatures for one node of a multi-mass model - ``files_def.py``: File naming conventions - ``/pars_.json``: Model coefficients for a model - ``minusz/pars_minusz.json``: Model coefficients for Minus-Z model - ``minusz/fit.*``: Outputs from fitting for Minus-Z model These tools depend on elements available via the Ska runtime environment, notably the engineering telemetry archive and the commanded states database. Multi-mass model definition ============================ The Chandra multi-mass thermal model allows for a linear coupling between an arbitrary number of mass nodes. It includes pitch-dependent heating and an ad-hoc constant thermal bath: .. image:: multimass.png In the actual model implementation the thermal mass (i.e. heat capacity) of each node is normalized to unity. That means that the coupling between two nodes is directional, i.e. U01 != U10. So heat flow from node 1 to 0 is governed by U10 while heat flow from 0 to 1 is governed by U01. This is mathematically equivalent to modeling independent heat capacities with U10 == U01. Updating model calibration =========================== The ``fit_nmass.py`` tool is used to update the calibration coefficients for a model. Usage: fit_nmass.py [options] Options: -h, --help show this help message and exit --days=DAYS Number of days in fit interval (default=90 --stop=STOP Stop time of fit interval (default=NOW - 7 days) --method=METHOD Fit method (default=simple) --model=MODEL Model to predict (default=minusz) --thaw-pars=THAW_PARS List of parameters (space-separated) to thaw (default=none) --nproc=NPROC Number of processors (default=1) --ftol=FTOL ftol convergence parameter (default=1e-4 --outdir=OUTDIR Output directory within root (default=fit) --pardir=PARDIR Directory containing model params file (default=) --quiet Suppress screen output --nofit Do not fit (default=False) --stored-data=STORED_DATA Use stored states and telem data from this file instead of database and archive Outdir ------ The ``--outdir`` parameter is a little special and is configured to conveniently allow many trials of fitting. If the specified output directory already exists (e.g. ``minusz/fit``) then that directory is renamed to be ``/.`` where ```` is the next in sequence from any other similary named directories. As a specific example, one might find the following files within the ``minusz`` directory:: fit/ # Most recent fit trial fit.1/ # First fit trial fit.2/ # Second fit trial pars_minusz.json # Parameters that are used for model calculation Now if another fit trial is done using ``fit_nmass.py`` then ``fit`` will be renamed to ``fit.3`` and the new fit results will go in ``fit``. In this way the most recent results are always in ``fit`` but one has a chronological record of all trials. Get the source --------------- First untar copy of the latest of the ``nmass`` project tar file:: source /proj/sot/ska/bin/ska_envs.csh cd untar /proj/sot/ska/share/nmass/nmass-.tar.gz (If you are planning a calibration update then instead check out a copy of the ``nmass`` source repository and enter the ``nmass`` directory.) Single processor example ---------------------------- Fit the ``pf_*`` model parameters (Epoch 2010 solar inputs) for the TCYLFMZM and TEPHIN nodes over the date range 2010:001 to 2010:090:: ./fit_nmass.py --model=minusz --days=90 --stop=2010:090 --outdir fit \ --thaw-pars="tcylfmzm__pf_.* tephin__pf_.*" This will generate a new set of model coefficients named ``pars_minusz.json`` in the ``minusz/fit`` directory. You can look at a web summary of the results with something like:: firefox minusz/fit/index.html If the new coefficients and the fit results are acceptable then copy those new coefficients to the like-named file in the ``minusz/`` directory. Then commit the updated file to the source control repository and distribute the file to the FOT for update of the MATLAB model. A normal "full" calibration update would consist of fitting for the all the Epoch 2010 solar inputs as well as the inter-node couplings over the last 360 days:: ./fit_nmass.py --model=minusz --days=360 --thaw-pars="t.*__pf_.* t.*__tau_t.*" Multi-processor example ------------------------ When fitting more than about 3-6 months of data it can be useful to take advantage of multiple processors. The ``fit_nmass.py`` script is written to allow this. First, you need to start up the MPD servers on the host machines. The hosts can be either on the localhost or remote machines. The only requirement is that you be able to access them via ``rsh`` (e.g. ``rsh remote_host ls``). In order to start a single MPD server process on the ``ccosmos`` machine which can allow up to 16 child processes do:: ska # NEED full ska environment mpdboot -r rsh --totalnum=1 --file=hosts/ccosmos --verbose --maxbranch=16 The following example will start 4 MPD server processes (each on a different node selected from hosts/mine) that can create up to a total of 12 child processes (3 per node):: mpdboot -r rsh --totalnum=5 --file=hosts/mine --verbose --maxbranch=12 To confirm that the servers have started as expected do:: mpdtrace Now do a fit including the ``--nproc`` option which can be any number up to the ``--maxbranch`` value set above:: python fit_nmass.py --days=180 --stop=2010:090 --nproc=4 --model=fssac If the process hangs up then kill with the ``kill `` command. If this doesn't seem to work then use ``kill -9 ``. In the worst case shut down the servers (see below) and hopefully all the zombie child processes will die. Be sure to check on the remote hosts that this is the case (``ps auxwww | grep fit``). Finally the MPD servers should be shut down:: mpdallexit This usually generates a warning/error message which can be ignored. Model validation ------------------ The ``fit_nmass.py`` tool can be used for model validation to check the accuracy of predictions. This is done with the ``--nofit`` option:: python fit_nmass.py --stop=2010:330 --days=30 --nofit --outdir validation This generates all the usual fit output plots using the current model parameters ``/pars_json``. If the ``--stop`` parameter is not supplied then the validation plot covers the time range that stops 7 days before the current time. Tools ==================== .. toctree:: :maxdepth: 2 nmass