diff --git a/.buildinfo b/.buildinfo index 63789a7f5..2d9a3cb8f 100644 --- a/.buildinfo +++ b/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 2c24b65e67ccd3c4ebc881facc088f93 +config: 92437fd7eaa6b9ccb2c30a864c924913 tags: fbb0d17656682115ca4d033fb2f83ba1 diff --git a/_sources/basics/dependencies_unix.txt b/_sources/basics/dependencies_unix.txt new file mode 100644 index 000000000..5a52b3e7c --- /dev/null +++ b/_sources/basics/dependencies_unix.txt @@ -0,0 +1,76 @@ + +.. summary Information on how to install some of the Cyclus dependencies + +Installing Dependencies on Unix +------------------------------- + +*Note that `unix` includes linux and darwin (mac) based systems* + +This page will provide a short walk-through of some of the non-standard +installation requirements for *Cyclus* dependencies. *Cyclus* strives to be a +modularly designed code that allows dynamic loading of modules at run time; +therefore, dependencies must be built as shared object libraries instead of +static libraries. This is done through the use of the -fPIC (position +independent code) flag when building the required dependencies. For your +edification, `this website `_ +has a good review of shared libraries in general. + +Some Quick Notes of Great Import +-------------------------------- + + #. The following procedures will NOT work correctly if you have already + acquired Lapack, BLAS, or Trilinos via Ubuntu's Synaptic Package Manager. + + * It is highly reccommended that you remove these libraries via Synaptic + before reinstalling them in the following manner. + + #. It is highly reccommended (specifically for novice users) that you install + these libraries in /usr/local + + #. Be very careful when using Teuchos. They have made the design decision to + include definitions in their header files (due to heavy use of templates). + Such header files can only be included in one location in the *Cyclus* source + code. + +Lapack +------ + +Lapack can be installed on your Unix machine using the following steps: + + #. Download Lapack from its `website `_ and untar it in a preferred location + #. Make a build directory (e.g. one can place the source code in ../lapack/lapack-xx.yy.zz-Source and make the directory .../lapack/build) + #. Copy the configure_lapack script located in the *Cyclus* repository located in /trunk/dependencies/lapack and place it in your build folder + #. Change the configure script so that the last line points to your lapack source (e.g. ../lapack/lapack-xx.yy.zz-Source) + + * Note, by default the script will install the library at /usr/local. + + #. Run the script (by typing ./configure_lapack.sh). Note that you may need to alter the script's permissions. To do so you can type "chmod 775 configure_lapack.sh". + #. From the build directory, type "make" (or "make -jN" where N is the number of threads you want to use [this speeds up the process]) + #. From the build directory, type "make install" + +Note that the making process can take some time. It is suggested that you make +with the `-j` flag. + +Teuchos +------- + +*Cyclus* uses the Teuchos_ package of Trilinos_. Teuchos can be installed on your Unix machine using the following steps: + + #. Download Trilinos from its website__ and untar it in a preferred location + #. Make a build directory (e.g. one can place the source code in .../trilinos/trilinos-xx.yy.zz-Source and make the directory .../trilinos/build) + #. Copy the configure_trilinos script located in the *Cyclus* repository located in /svn/dependencies/trilinos and place it in your build folder + #. Change the configure script so that the last line points to your trilinos source (e.g. .../trilinos/trilinos-xx.yy.zz-Source) + + * Note, by default the script will install the library at /usr/local. + + #. Run the script (by typing ./configure_trilinos.sh). Note that you may need to alter the script's permissions. To do so you can type "chmod 775 configure_trilinos.sh". + #. From the build directory, type "make" (or "make -jN" where N is the number of threads you want to use [this speeds up the process]) + #. From the build directory, type "make install" + +.. _Teuchos: http://trilinos.sandia.gov/packages/teuchos/ + +.. _Trilinos: http://trilinos.sandia.gov/ + +__ Trilinos_ + + diff --git a/_sources/basics/dependencies_windows.txt b/_sources/basics/dependencies_windows.txt new file mode 100644 index 000000000..e8a79e596 --- /dev/null +++ b/_sources/basics/dependencies_windows.txt @@ -0,0 +1,123 @@ + +.. summary Information on how to install some of the Cyclus dependencies + +Installing Dependencies on Windows +================================== + +This page will provide a short walk-through of some of the installation +requirements for *Cyclus* dependencies on a Windows platform. *Cyclus* strives +to be a modularly designed code that allows dynamic loading of modules at run +time; therefore, most dependencies must be built as shared object libraries +instead of static libraries. + +Cygwin +------ + +Cygwin is a terminal program that simulates a linux-like environment on Windows +platforms. To install Cygwin_ you will need to download a setup file and run it +according to the instructions at the `Cygwin Install Page`_. + +.. _Cygwin: http://cygwin.com + +.. _`Cygwin Install Page`: http://cygwin.com/install.html + +Specifically, the Cygwin installation manager will walk through the +installation process: + + #. Select Install From Internet. + #. Choose a directory to install cygwin. + #. Choose a download mirror near you. + #. Choose packages to install + + * If you have two free gigabytes on your computer, the package + configuration process can be simplified by choosing to download all + packages. This will require clicking INSTALL the icon next to ALL. + + * If space is restricted, you may be more selective about packages. When + selecting packages, choose the default action for ALL packages. Then, + search for and select install for specific packages that cyclus and its + dependencies rely on : svn, gcc, g++, g77, cmake, make, lapack, libxml2, + libidn. + + #. This will take some time to install + #. When installed, check that these were installed correctly by using the 'which' command. A path will be returned if the package is found. If not, rerun Cygwin's setup.exe and install just the packages that are not found. + + * To check for svn, open a Cygwin terminal and type 'which svn'. + * To check for gcc, open a Cygwin terminal and type 'which gcc' + * etc. + +Boost +----- + +Cyclus depends on boost. You may install boost following instructions at the +`Boost website`_. It is recommenced that Windows users use the boost installer +executable rather than unpacking the binaries manually or building from source. +So, download the installer. + +.. _`Boost website`: http://www.boost.org + +#. When the installer asks what packages to install, be certain to include + + * the program_options library + * the IOStream libraries + * and the date_time library + * in addition to the default header libraries. + +#. If you have surplus space on your computer, don't hesitate to install all of the libraries available, but be prepared for the installation to take up to an hour for all packages. +#. The installer will ask what variants of the boost libraries to install. Be certain to install a dynamic and a static library. Threading is up to you. + +HDF5 +---- + +HDF5 is a hierarchical database library that Cyclus uses for record keeping. To +install HDF5 on Windows : + + #. Go to the hdf5 website. + #. Download the appropriate precompiled Windows binaries. + #. Extract the full directory structure somewhere temporary. + #. Move the contents of the resulting /bin directory to /usr/local/bin , or another preferred bin directory in your $PATH . + #. Move the contents of the /lib directory to /usr/local/lib (or elsewhere in your $PATH). + #. So too with the contents of the include directory, move them to /usr/local/include (or elsewhere). + #. This can optionally be repeated with the share directory as well. + +Make sure the location you placed the binary files is in your $PATH environment +variable. Finally, add an environment variable that states $HDF5_ROOT = +/usr/local/lib (or your favorite other location). + +Teuchos +------- + +Download the Trilinos source code to some location such as ~/trilinos_source . + +If CMake fails to find your c, cxx, or fortran compilers, double check that +these are in your path. You may also inform CMake of your default compilers +with environment variables that CMake pays attention to. To set the C compiler, +for example, you would set the $CC environmet variable to /usr/bin/gcc-3 . + +Running cmake:: + + cd ~/trilinos_source + cd ../ + mkdir trilinos_build + cd trilinos_bild + cmake-gui ../trilinos_source + +From the gui (or via commandline flags, if you prefer), set the following +advanced configuration flags for the Trilinos build: + + * BUILD_SHARED_LIBS=ON + * CMAKE_INSTALL_PREFIX=/usr/local/ (or elsewhere) + * Trilinos_ENABLE_TEUCHOS=ON + * BLAS_LIBRARY_DIRS=/usr/lib + * LAPACK_LIBRARY_DIRS=/usr/lib + * BLAS_LIBRARY_NAMES="blas" + * LAPACK_LIBRARY_NAMES="lapack" + +Finally, configure and generate the make file (in the gui, these are buttons). +In the terminal type make, then type make install. + +Now What? +--------- + +You're now ready to build cyclus. Onward to GettingAndBuildingCyclus. + diff --git a/_sources/basics/get_and_build.txt b/_sources/basics/get_and_build.txt index 368b95cdd..e644c979d 100644 --- a/_sources/basics/get_and_build.txt +++ b/_sources/basics/get_and_build.txt @@ -21,8 +21,13 @@ Package Minimum Version ==================== ================== An overview of some more complicated package builds and installations (e.g. -lapack, teuchos, etc.) can be found on the InstallingDependenciesOnUnix or -InstallingDependenciesOnWindows wiki pages. +lapack, teuchos, etc.) can be found on the following pages: + +.. toctree:: + :maxdepth: 2 + + dependencies_unix + dependencies_windows Project Repository ------------------ diff --git a/_sources/basics/main.txt b/_sources/basics/main.txt index 283706ebc..6b27d2079 100644 --- a/_sources/basics/main.txt +++ b/_sources/basics/main.txt @@ -8,7 +8,6 @@ Cyclus Fundamentals introduction get_and_build - style_guide decay .. stuff not converted yet diff --git a/source/devdoc/CyclusStyleGuidelines.rst b/_sources/basics/style_guide.txt similarity index 83% rename from source/devdoc/CyclusStyleGuidelines.rst rename to _sources/basics/style_guide.txt index 35bb8737d..f749d3e73 100644 --- a/source/devdoc/CyclusStyleGuidelines.rst +++ b/_sources/basics/style_guide.txt @@ -1,7 +1,8 @@ -.. summary Style Guidelines for cyclus development -Cyclus Style Guidelines -======================= +.. summary Style Guidelines for cyclus developers + +Style Guidelines for Developers +=============================== The purpose of this page is to introduce some general style guidelines to help with readability, maintainability and extensibility of the cyclus code base. @@ -10,6 +11,7 @@ with readability, maintainability and extensibility of the cyclus code base. Class File Organization ----------------------- + Class header files should be organized in the following order: * private @@ -17,32 +19,24 @@ Class header files should be organized in the following order: * methods * virtual - * static - * non-static * data members * static - * non-static * protected (in same order as above) - * public (in same order as above) Within each section, methods should be grouped and ordered in logical categories in the following order: * "life-cycle" methods first (e.g. constructors, destructors, initializers) - * operators (e.g. equivalence, assignment) - * data access methods - * other base-class-specific categories - * other class-specific categories The order of method definition in the implementation file should be consistent @@ -56,8 +50,6 @@ style standard as much as possible. This requires that all tabs be replaced by spaces, and that an indentation is equal to two spaces. Further information on this style standard can be found in the `Google Style Guide`_. -.. _`Google Style Guide`: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml - Notable items: * no tabs - expand all tabs to 2 spaces. @@ -66,9 +58,9 @@ Notable items: * trailing underscores must be used with all class member variables - * opening braces should be placed on the same line as function args: - `ReturnType functionName(Arg1Type arg_name) {` - - * loop and branching statements should generally use the opening and closing - braces (i.e. not like this: `if (true) long_statement;`) + * opening braces should be placed on the same line as function args: `ReturnType functionName(Arg1Type arg_name) {` + + * loop and branching statements should use the opening and closing braces (i.e. not like this: `if (true) long_statement;`) + +.. _`Google Style Guide`: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml diff --git a/_sources/devdoc/flow_and_structure.txt b/_sources/devdoc/flow_and_structure.txt new file mode 100644 index 000000000..73442e4ba --- /dev/null +++ b/_sources/devdoc/flow_and_structure.txt @@ -0,0 +1,116 @@ + +.. summary Describe & Design Program Flow and Data Structures + +Program Flow and Data Structures +================================ + +Program Flow Overview ++++++++++++++++++++++ + +Execution flow outline: + + #. Read input + #. Setup model + #. Start time steps + + * `The Tick`_: collect offers/requests + * `Market Resolution`_ + * `The Tock`_: distribute material objects + +Simulation Initialization +------------------------- + + #. Load markets based on market models + + #. for each market + + #. check whether the model for this market has been loaded already, and load if necessary + #. instantiate new market and initialize parameters + + #. Assign commodities to markets + + #. Load facilities based on facility models + + #. for each facility + + #. check whether the model for this facility has been loaded already, and load if necessary + #. instantiate a template for a new facility based on input parameters + + #. assign commodities to facilities and cross-reference with markets + + #. add template to facility template map + + #. Load regions based on region models + + #. for each region + + #. check whether the model for this region has been loaded already, and load if necessary + #. instantiate new region and initialize parameters + #. create list of available facility templates for that region + + #. Load simulation parameters + +Facility Deployment +------------------- + +When and how does facility deployment happen, based on the list of facility +templates? + +The Tick +-------- + + # cycle through Regions + # cycle through Institutions + # deploy new facilities as necessary + # cycle through facilities + # update facility state as appropriate + # prompt for requests/offers + +Market Resolution +----------------- + + * convert sets of requests/offers into sets of material transactions + +The Tock +-------- + + #. cycle through Markets + + #. cycle through transactions + + #. preform material transactions + #. update facility state as appropriate + +Data Structure Overview ++++++++++++++++++++++++ + +Abstract Base Classes +--------------------- + +Communicator +~~~~~~~~~~~~ + +Provides all functionality for message passing among facilities and markets, +including offers/requests and transactions. + +Facility +~~~~~~~~ + +Provides base definition of facility and standard interface. All derived +classes must implement this interface cleanly so that they can operate as +plug-in modules. + +Market +~~~~~~ + +Provides base definition of a market and standard interface. All derived +classes must implement this interface cleanly so that they can operate as +plug-in modules. + +Region +~~~~~~ + +Provides base definition of a region and standard interface. All derived +classes must implement this interface cleanly so that they can operate as +plug-in modules. + diff --git a/_sources/devdoc/main.txt b/_sources/devdoc/main.txt index c3e460e09..ba7e713b3 100644 --- a/_sources/devdoc/main.txt +++ b/_sources/devdoc/main.txt @@ -11,14 +11,16 @@ in a variety of forms. If you haven't already, check out Getting Started --------------- +First things first - read :doc:`../basics/get_and_build`. After +successfully acquiring and building *Cyclus*, you can begin developing: + .. toctree:: :maxdepth: 2 - ../basics/get_and_build - CyclusStyleGuidelines + style_guide make-models/main - ProgramFlowAndDataStructureOverview - OutputDatabase + flow_and_structure + output_dbase Doxygen Code Documentation -------------------------- diff --git a/_sources/devdoc/make-models/facility.txt b/_sources/devdoc/make-models/facility.txt new file mode 100644 index 000000000..c99b59814 --- /dev/null +++ b/_sources/devdoc/make-models/facility.txt @@ -0,0 +1,34 @@ + +.. summary Developers notes for the implementation of a new FacilityModel + +Developing Region Models +======================== + +After reading GuidelinesForImplementingNewModels, this should provide +additional information specific to implementing a new FacilityModel. + +Details +------- + +In addition to inheriting from the main dynamic loading base class `Model`, all +FacilityModel models also inherit from `Communicator`. + +A FacilityModel is one of the primary actors in the *Cyclus* system. All +offers and requests originate at an instance of a FacilityModel and all +shipments are executed by an instance of a FacilityModel. + +While running, *Cyclus* will use a FacilityModel in two ways. First, it will +read user input to define a template instance of a FacilityModel. A choice of +a FacilityModel model combined with some distinct set of parameters for that +model results in a facility that is available for deployment by an InstModel +institution if allowed by that institution's RegionModel region. Second, +*Cyclus* will create copies of the FacilityModel facilities as they are +deployed by the institutions. For this reason, the FacilityModel class defines +a data member `fac_name` that is the name of the individual deployed facility. + +All FacilityModel models should know which set of Commodity objects they trade +and/or which MarketModel markets they participate in. Each FacilityModel model +should implement a method named `sendMessages` to generate offer and request +messages to send to their markets and methods named `sendMaterial` and +`receiveMaterial` to process shipment messages that originate with their +markets. diff --git a/_sources/devdoc/make-models/institution.txt b/_sources/devdoc/make-models/institution.txt index 505c81627..e82e8f32c 100644 --- a/_sources/devdoc/make-models/institution.txt +++ b/_sources/devdoc/make-models/institution.txt @@ -1,6 +1,34 @@ +.. summary Developers notes for the implementation of a new InstModel + Developing Institution Models ============================= +After reading GuidelinesForImplementingNewModels, this should provide +additional information specific to implementing a new InstModel. + +Details +------- + +In addition to inheriting from the main dynamic loading base class `Model`, all +InstModel models also inherit from `Communicator`. + +A InstModel's primary function is to + + * refer to the set of facilities operating in this institution + +All InstModel models may also implement a reciveMessage function if messages +need to be amended by the institution before being sent up to the region or +down to the facility. This is a virtual (but not pure virtual) function, so +implementation is optional. Default behavior is to ignore the message. + +InstModel models are sent a tick and tock signal at the beginning and end of +each month, respectively. Monthly tasks, such as facility deployment or +bookkeeping should be undertaken within the handleTick and handleTock +functions. These are virtual (but not pure virtual), so implementation of these +functions is optional. + + *The InstModel model type is not yet stable and additional interface and + data members are expected to be added.* diff --git a/_sources/devdoc/make-models/market.txt b/_sources/devdoc/make-models/market.txt index c87e1e5ab..c34450396 100644 --- a/_sources/devdoc/make-models/market.txt +++ b/_sources/devdoc/make-models/market.txt @@ -1,4 +1,35 @@ +.. summary Developers notes for the implementation of a new MarketModel + Developing Market Models ======================== +After reading GuidelinesForImplementingNewModels, this should provide +additional information specific to implementing a new MarketModel. + +Details +------- + +In addition to inheriting from the main dynamic loading base class `Model`, all +MarketModel models also inherit from `Communicator`. + +A MarketModel's primary function is to + + * receive offers and requests from facilities, + + * *resolve* the market by matching those offers and requests + + * generate/execute a set of orders for shipments of material between + facilities that results from resolving the market + +Therefore, all MarketModel models should implement their own version of +`receiveOfferRequest` that registers incoming offers and requests in a way that +is appropriate for this market implementation. All MarketModel models must +also implement their own version of `resolve`. + +All MarketModel models have an STL `set` of pointers to the `OfferRequest` +messages that have arrived and an STL `deque` of pointers to the `Shipment` +messages that it is generating. MarketModel models are also free to have +additional storage modes for `OfferRequest` messages or `Shipment` messages +that facilitates the operation of that particular MarketModel paradigm. + diff --git a/_sources/devdoc/make-models/region.txt b/_sources/devdoc/make-models/region.txt new file mode 100644 index 000000000..aeb984af2 --- /dev/null +++ b/_sources/devdoc/make-models/region.txt @@ -0,0 +1,50 @@ + +.. summary Developers notes for the implementation of a new RegionModel + +Developing Region Models +======================== + +After reading GuidelinesForImplementingNewModels, this should provide +additional information specific to implementing a new RegionModel. + +Details +------- + +In addition to inheriting from the main dynamic loading base class `Model`, all +RegionModel models also inherit from `Communicator`. + +A RegionModel's primary functions are to + + * contain a set of institutions that operate in this region + * define a set of allowed facilities for those institutions + * Schedule the deployment of facilities by either + + #. Determining when new facilities need to be built, or + #. deferring to an InstModel to make this determination. + + * Manage the deployment of facilities by interacting with the Institutions to select a specific facility type and facility parameters + * Passing material offers/requests between a prescribed market and related facilities. + +All RegionModel models have an STL `set` of pointers to the `Model` instances +that represent the allowed FacilityModel facilities. and an STL `vector` of +pointers to the `Model` instances that represent the contained InstModel +institutions. + +All RegionModel models may also implement a reciveMessage function if messages +need to be amended by the region before being sent up to the market or down to +the institution. This is a virtual (but not pure virtual) function, so +implementation is optional. Default behavior is to ignore the message. + +RegionModel models are sent a tick and tock signal at the beginning and end of +each month, respectively. Monthly tasks, such as facility deployment or +bookkeeping should be undertaken within the handleTick and handleTock +functions. These are virtual (but not pure virtual), so implementation of these +functions is optional. + +To Do +----- + +RegionModel models should be the mechanism for implementing demand growth. +Different implementations of RegionModel models might implement different ways +to model that growth. (Or is this all pre-processing?) + diff --git a/_sources/devdoc/output_dbase.txt b/_sources/devdoc/output_dbase.txt new file mode 100644 index 000000000..b0a62855c --- /dev/null +++ b/_sources/devdoc/output_dbase.txt @@ -0,0 +1,276 @@ + +.. summary Design Goals for the Output Database + +Output Database +=============== + +*Cyclus* simulations are comprised of three major constructs (the interaction +of which we are interested in documenting). In *Cyclus*, **Agents** create +**Resources** and then trade these resources via **Transactions**. Accordingly, +the output database is nominally divided into three catagories: Agents, +Resources, and Transactions. The *Cyclus* database has been designed with three +key concepts in mind: we wish for *Cyclus* to be extensible, i.e. we do not +want to hinder the development of a new module, we wish for the output data +structures to be as straight-forward as possible to reduce hindrince of +post-processing, and we wish for the database to be efficient. With these three +goals in mind, we have developed a the database structure that sacrifices some +amount of size (i.e., there are multiple entries per table which could be +consolidated) in order to allow for greater flexibility and readability (i.e. +natural intuition of where to look for a given data object). In this database +paradigm, for example, an external developer has the ability to create a new +agent type, and retrieve any information he/she wishes with regard to output. +The database structure does not stunt a developer's ability or creativity. + +Provenance +---------- + +Good provenance will be provided by an output database with sufficient data to +allow reproducibility of the results. This robust reproducibility is essential +to the scientific effort. In the case of *Cyclus*, the inclusion of a complete +notion of the input specifications in the output database will be sufficient to +allow for result reproduction as well as facilitate knowledge sharing, +post-simulation analysis and error-checking. Such input specifications include +a complete description of the simulation parameters and model configurations +defined in the input. + +Database Structure +------------------ + +As previously mentioned, *Cyclus* deals in three basic constructs: agents, +resources, and transactions. A transaction in *Cyclus* is relatively static, +i.e. every transaction has the same basic information (for example: who is the +sender, who is the receiever, what was transacted, etc.). Conversely, agents +and resources are highly variable. We therefore allow for each /implementation/ +of an agent (e.g. a Facility Agent) and each /type/ of resource (e.g. a +Material) to have both **Static** and **Dynamic** tables associated with them. +As will be outlined in detail below, the output database structure of a +*Cyclus* simulation will have, in general, the following heirarchichal +structure: + + * /output/agents + * /output/agents/implementation/staticParams + * /output/agents/implementation/variableParams + * /output/resources + * /output/resources/type/staticParams + * /output/resources/type/variableParams + * /output/transactions + +Accordingly, there are currently seven primary tables in the *Cyclus* output +database: + + * `Agent Description Table`_ + * `Agent Static State Parameter Table`_ + * `Agent Variable State Parameter Table`_ + * `Resource Description Table`_ + * `Resource Static State Parameter Table`_ + * `Resource Variable State Parameter Table`_ + * `Transaction Description Table`_ + +Agent Description Table +----------------------- + +This table contains the generic information of each agent and information +regarding its time of creation and deletion. The table parameters are the +following: + + * the agent's unique ID + * the agent's parent's unique ID + * the agent's type (e.g., Region, Institution, Market, etc.) + * the agent's implementation (e.g., SourceFacility, NullRegion, GreedyMarket, etc.) + * a timestamp of the agent's birth + * a timestamp of the agent's death + +Note that there is one entry for each unique agent. + +As an example, let us assume that a agent X of type is owned by an agent Y and is created at time t1. Agent X has type T and implementation I and ends its service at time t2. The table entry is as follows: + +======== ========= ==== ============== ===== ===== +Agent ID Parent ID Type Implementation Birth Death +======== ========= ==== ============== ===== ===== +X Y T I t1 t2 +======== ========= ==== ============== ===== ===== + +Agent Static State Parameter Table +---------------------------------- + +This table contains information about specific instances of agents that **do +not change** with time. This table is unique to each different +**implementation** of agent. For instance, a Reactor may have the following +class hierarchy: Agent -> Facility -> Reactor. Accordingly, there will be a +data entry for the Reactor in each table, with the reactor-specific information +placed in the Reactor table. There are some tables which are associated with +the *Cyclus* core, and thus will have an immutable form at each release (e.g. +Regions, Institutions, Facilities, Markets). It is the responsibility of each +developer to guarantee that their module output corresponds to this +hierarchical structure if it is to be included in a *Cyclus* release. + +Let us take the SourceFacility as it currently exists in *Cyclus*. It has, +nominally, three static members: its monthly production capacity, its total +inventory size, and its output commodity. For this example, let us assume that +SourceFacility X has a maximum production capacity of Y kg/month of commodity C +and has a maximum inventory size of Z kg. Its static state parameter table, +located at /output/agents/SourceFacility/staticParams would therefore look like +the following: + +======== ========= ======== ============== ========= =============== +Agent ID Commodity Capacity Capacity Units Inventory Inventory Units +======== ========= ======== ============== ========= =============== +X C Y kg/month Z kg +======== ========= ======== ============== ========= =============== + + +Agent Variable State Parameter Table +------------------------------------ + +This table is similar to the static parameter table described above, containing +information about specific instances of agents that **do change** with time. +This table is unique to each different **implementation** of agent. For +instance, a Reactor may have the following class hierarchy: Agent -> Facility +-> Reactor. Accordingly, there will be a data entry for the Reactor in each +table, with the reactor-specific information placed in the Reactor table. There +are some tables which are associated with the *Cyclus* core, and thus will have +an immutable form at each release (e.g. Regions, Institutions, Facilities, +Markets). It is the responsibility of each developer to guarantee that their +module output corresponds to this hierarchical structure if it is to be +included in a *Cyclus* release. + +Let us continue with the above example. An optional parameter for the +SourceFacility is the capacity factor, i.e. the percentage of maximum capacity +Y is the facility able to operate at some time t. For this example, let us +assume that at time t1, SourceFacility X begins operation with capacity factor +0.95 and must go down for maintenence at time t2, reducing its capacity factor +to 0.00. Its variable state parameter table, located at +/output/agents/SourceFacility/variableParams would therefore look like the +following: + +======== =============== ========= ==== +Agent ID Capacity Factor CF Units Time +======== =============== ========= ==== +X 0.95 decimal % t1 +X 0.00 decimal % t2 +======== =============== ========= ==== + +Note that there may be multiple entries per agent in this table. + +Additionally note that the timestamping works in the following manner: if the +timestamp is equal to the agent's birth time stamp, then this is the first +occurance of the variable parameter; if it is not, then one may assume that the +parameter did not change during the period between two timestamps. + + +Resource Description Table +-------------------------- + +This table contains the generic information of each resource and information +regarding its time of creation and deletion. The table parameters are the +following: + + * the resource's unique ID + * the resource's creating agent's unique ID + * the resource's type (material, man-hours, etc.) + * the resource's base unit (kg, hours, etc.) + * a timestamp of the resource's birth + * a timestamp of the resoruce's death (i.e., when it is consumed, etc.) + +For example, let us assume that facility with unique ID X, creates a resource +of type T at time t1 whose unique ID is Y, in addition, let us assume that the +base unit type is kilograms. Finally, let us assume that the resource is +eventually consumed by a chemical process (e.g., used-fuel being reprocessed) +at time t2. The table entry for this resource is as follows: + +=========== ============== ==== ==== ===== ===== +Resource ID Creating Agent Type Unit Birth Death +=========== ============== ==== ==== ===== ===== +R X T kg t1 t2 +=========== ============== ==== ==== ===== ===== + + +Resource Static State Parameter Table +------------------------------------- + +This table contains information about specific instances of resources that **do +not change** with time. This table is unique to each different +**implementation** of a resource. For instance, UO,,2,, may have the following +class hierarchy: Resource -> Material -> UO2. Accordingly, there will be a data +entry for the UO,,2,, in each table, with the UO,,2,,-specific information +placed in the UO2 table. There are some tables which are associated with the +*Cyclus* core, and thus will have an immutable form at each release (e.g. +Material). It is the responsibility of each developer to guarantee that their +module output corresponds to this hierarchical structure if it is to be +included in a *Cyclus* release. + +Let us use the Material class as an example. The static table for the material +resource is relatively straight-forward (most of the work is done by the +dynamic table). As a convention in *Cyclus*, we do not allow Materials to +change form (in order for a Material to change form, the original resource must +be destroyed and a new resource created). Let us assume that some material +resource with ID R (and type Material) has the form uo2. + +=========== ======== +Resource ID Form +=========== ======== +R UO,,2,, +=========== ======== + + +Resource Variable State Parameter Table +--------------------------------------- + +This table contains information about specific instances of resources that **do +change** with time. This table is unique to each different **implementation** +of a resource. For instance, UO,,2,, may have the following class hierarchy: +Resource -> Material -> UO2. Accordingly, there will be a data entry for the +UO,,2,, in each table, with the UO,,2,,-specific information placed in the UO2 +table. There are some tables which are associated with the *Cyclus* core, and +thus will have an immutable form at each release (e.g. Material). It is the +responsibility of each developer to guarantee that their module output +corresponds to this hierarchical structure if it is to be included in a +*Cyclus* release. + +We choose to provide the following example. Suppose some facility receives N +kilograms of Used UO,,2,, at time t1 /and/ that Used UO,,2,, has the ability to +decay, i.e. it is radioactive. Consider the following two scenarios: + + #. sufficient time has passed to take into account the decay of the Used UO,,2,, + #. an amount, n, of the Used UO,,2,, is traded to another agent + +For simplicity, we assume that used UO,,2,, is comprised of only ^16^O and +^235^U. The decay isotopics are meaningless and only meant to be a qualitative +example. + +=========== ===== =========== =========== ================= ========= +Resource ID Mass Isotopics Composition Composition Units Timestamp +=========== ===== =========== =========== ================= ========= +R N 8016, 92235 0.33, 0.67 atomic t1 +R N 8016, 92235 0.34, 0.66 atomic t2 +R N - n 8016, 92235 0.34, 0.66 atomic t3 +=========== ===== =========== =========== ================= ========= + +Note that there may be multiple entries per agent in this table. + + +Transaction Description Table +----------------------------- + +This table contains the generic information of each transaction. The table +parameters are the following: + + * the transaction's unique ID + * the sending agent's unique ID + * the receiving agent's unique ID + * the resource being transacted + * the price for the transaction (assumed going from receiver to sender) + * the timestamp of the transaction + +For example, let us assume agent X sends resource R to agent Y at time t for +price P, and the transactions unique ID is U. The table entry, at +/output/transactions/, would be as follows: + +============== ====== ======== ======== ===== ========= +Transaction ID Sender Receiver Resource Price Timestamp +============== ====== ======== ======== ===== ========= +U X Y R P t +============== ====== ======== ======== ===== ========= + +Note that it is assumed that the amount is in the resource's base unit. + diff --git a/_sources/devdoc/style_guide.txt b/_sources/devdoc/style_guide.txt new file mode 100644 index 000000000..f749d3e73 --- /dev/null +++ b/_sources/devdoc/style_guide.txt @@ -0,0 +1,66 @@ + +.. summary Style Guidelines for cyclus developers + +Style Guidelines for Developers +=============================== + +The purpose of this page is to introduce some general style guidelines to help +with readability, maintainability and extensibility of the cyclus code base. + + +Class File Organization +----------------------- + + +Class header files should be organized in the following order: + + * private + + * methods + + * virtual + * static + * non-static + + * data members + + * static + * non-static + + * protected (in same order as above) + * public (in same order as above) + +Within each section, methods should be grouped and ordered in logical +categories in the following order: + + * "life-cycle" methods first (e.g. constructors, destructors, initializers) + * operators (e.g. equivalence, assignment) + * data access methods + * other base-class-specific categories + * other class-specific categories + +The order of method definition in the implementation file should be consistent +with the order of declaration in the header file. + +Code Formatting +--------------- + +Line lengths, tab spacing, and bracket placement will conform to the google c++ +style standard as much as possible. This requires that all tabs be replaced by +spaces, and that an indentation is equal to two spaces. Further information on +this style standard can be found in the `Google Style Guide`_. + +Notable items: + + * no tabs - expand all tabs to 2 spaces. + + * enum items should be all caps + + * trailing underscores must be used with all class member variables + + * opening braces should be placed on the same line as function args: `ReturnType functionName(Arg1Type arg_name) {` + + * loop and branching statements should use the opening and closing braces (i.e. not like this: `if (true) long_statement;`) + +.. _`Google Style Guide`: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml + diff --git a/_static/header-image.png b/_static/header-image.png new file mode 100644 index 000000000..d5ff915b2 Binary files /dev/null and b/_static/header-image.png differ diff --git a/basics/decay.html b/basics/decay.html index bbbffbbf0..d679e9a52 100644 --- a/basics/decay.html +++ b/basics/decay.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Radioactive Decay in Cyclus — Cyclus + Radioactive Decay in Cyclus — Cyclus Home @@ -25,12 +26,17 @@ - + +
+ +
+ +

Navigation

-

Table Of Contents

diff --git a/basics/dependencies_unix.html b/basics/dependencies_unix.html new file mode 100644 index 000000000..4ace7218c --- /dev/null +++ b/basics/dependencies_unix.html @@ -0,0 +1,200 @@ + + + + + + + + + + + Installing Dependencies on Unix — Cyclus Home + + + + + + + + + + + + + + +
+ +
+ + +
+

Navigation

+ +
+
+
+

Table Of Contents

+ + +

Previous topic

+

Getting and Building Cyclus

+

Next topic

+

Installing Dependencies on Windows

+ + +
+
+ +
+
+
+
+ +
+

Installing Dependencies on Unix

+

Note that `unix` includes linux and darwin (mac) based systems

+

This page will provide a short walk-through of some of the non-standard +installation requirements for Cyclus dependencies. Cyclus strives to be a +modularly designed code that allows dynamic loading of modules at run time; +therefore, dependencies must be built as shared object libraries instead of +static libraries. This is done through the use of the -fPIC (position +independent code) flag when building the required dependencies. For your +edification, this website +has a good review of shared libraries in general.

+
+
+

Some Quick Notes of Great Import

+
+
    +
  1. The following procedures will NOT work correctly if you have already +acquired Lapack, BLAS, or Trilinos via Ubuntu’s Synaptic Package Manager.
      +
    • It is highly reccommended that you remove these libraries via Synaptic +before reinstalling them in the following manner.
      • +
    +
    2. +
  2. It is highly reccommended (specifically for novice users) that you install +these libraries in /usr/local
    3. +
  3. Be very careful when using Teuchos. They have made the design decision to +include definitions in their header files (due to heavy use of templates). +Such header files can only be included in one location in the Cyclus source +code.
    4. +
+
+
+
+

Lapack

+

Lapack can be installed on your Unix machine using the following steps:

+
+
    +
  1. Download Lapack from its website and untar it in a preferred location
    2. +
  2. Make a build directory (e.g. one can place the source code in ../lapack/lapack-xx.yy.zz-Source and make the directory .../lapack/build)
    3. +
  3. Copy the configure_lapack script located in the Cyclus repository located in /trunk/dependencies/lapack and place it in your build folder
    4. +
  4. Change the configure script so that the last line points to your lapack source (e.g. ../lapack/lapack-xx.yy.zz-Source)
    5. +
+
+
    +
  • Note, by default the script will install the library at /usr/local.
    • +
+
+
    +
  1. Run the script (by typing ./configure_lapack.sh). Note that you may need to alter the script’s permissions. To do so you can type “chmod 775 configure_lapack.sh”.
    2. +
  2. From the build directory, type “make” (or “make -jN” where N is the number of threads you want to use [this speeds up the process])
    3. +
  3. From the build directory, type “make install”
    4. +
+
+

Note that the making process can take some time. It is suggested that you make +with the -j flag.

+
+
+

Teuchos

+

Cyclus uses the Teuchos package of Trilinos. Teuchos can be installed on your Unix machine using the following steps:

+
+
    +
  1. Download Trilinos from its website and untar it in a preferred location
    2. +
  2. Make a build directory (e.g. one can place the source code in .../trilinos/trilinos-xx.yy.zz-Source and make the directory .../trilinos/build)
    3. +
  3. Copy the configure_trilinos script located in the Cyclus repository located in /svn/dependencies/trilinos and place it in your build folder
    4. +
  4. Change the configure script so that the last line points to your trilinos source (e.g. .../trilinos/trilinos-xx.yy.zz-Source)
    5. +
+
+
    +
  • Note, by default the script will install the library at /usr/local.
    • +
+
+
    +
  1. Run the script (by typing ./configure_trilinos.sh). Note that you may need to alter the script’s permissions. To do so you can type “chmod 775 configure_trilinos.sh”.
    2. +
  2. From the build directory, type “make” (or “make -jN” where N is the number of threads you want to use [this speeds up the process])
    3. +
  3. From the build directory, type “make install”
    4. +
+
+
+ + +
+
+
+
+
+
+

Navigation

+ +
+
+ © Copyright 2012, Robert Carlsen. + Created using Sphinx 1.1.2. +
+ + \ No newline at end of file diff --git a/basics/dependencies_windows.html b/basics/dependencies_windows.html new file mode 100644 index 000000000..dc292667c --- /dev/null +++ b/basics/dependencies_windows.html @@ -0,0 +1,247 @@ + + + + + + + + + + + Installing Dependencies on Windows — Cyclus Home + + + + + + + + + + + + + + +
+ +
+ + +
+

Navigation

+ +
+
+
+

Table Of Contents

+ + +

Previous topic

+

Installing Dependencies on Unix

+

Next topic

+

Radioactive Decay in Cyclus

+ + +
+
+ +
+
+
+
+ +
+

Installing Dependencies on Windows

+

This page will provide a short walk-through of some of the installation +requirements for Cyclus dependencies on a Windows platform. Cyclus strives +to be a modularly designed code that allows dynamic loading of modules at run +time; therefore, most dependencies must be built as shared object libraries +instead of static libraries.

+
+

Cygwin

+

Cygwin is a terminal program that simulates a linux-like environment on Windows +platforms. To install Cygwin you will need to download a setup file and run it +according to the instructions at the Cygwin Install Page.

+

Specifically, the Cygwin installation manager will walk through the +installation process:

+
+
    +
  1. Select Install From Internet.
    2. +
  2. Choose a directory to install cygwin.
    3. +
  3. Choose a download mirror near you.
    4. +
  4. Choose packages to install
    5. +
+
+
    +
  • If you have two free gigabytes on your computer, the package +configuration process can be simplified by choosing to download all +packages. This will require clicking INSTALL the icon next to ALL.
    • +
  • If space is restricted, you may be more selective about packages. When +selecting packages, choose the default action for ALL packages. Then, +search for and select install for specific packages that cyclus and its +dependencies rely on : svn, gcc, g++, g77, cmake, make, lapack, libxml2, +libidn.
    • +
+
+
    +
  1. This will take some time to install
    2. +
  2. When installed, check that these were installed correctly by using the ‘which’ command. A path will be returned if the package is found. If not, rerun Cygwin’s setup.exe and install just the packages that are not found.
      +
    • To check for svn, open a Cygwin terminal and type ‘which svn’.
      • +
    • To check for gcc, open a Cygwin terminal and type ‘which gcc’
      • +
    • etc.
      • +
    +
    3. +
+
+
+
+

Boost

+

Cyclus depends on boost. You may install boost following instructions at the +Boost website. It is recommenced that Windows users use the boost installer +executable rather than unpacking the binaries manually or building from source. +So, download the installer.

+
    +
  1. When the installer asks what packages to install, be certain to include
    2. +
+
+
    +
  • the program_options library
    • +
  • the IOStream libraries
    • +
  • and the date_time library
    • +
  • in addition to the default header libraries.
    • +
+
+
    +
  1. If you have surplus space on your computer, don’t hesitate to install all of the libraries available, but be prepared for the installation to take up to an hour for all packages.
    2. +
  2. The installer will ask what variants of the boost libraries to install. Be certain to install a dynamic and a static library. Threading is up to you.
    3. +
+
+
+

HDF5

+

HDF5 is a hierarchical database library that Cyclus uses for record keeping. To +install HDF5 on Windows :

+
+
    +
  1. Go to the hdf5 website.
    2. +
  2. Download the appropriate precompiled Windows binaries.
    3. +
  3. Extract the full directory structure somewhere temporary.
    4. +
  4. Move the contents of the resulting /bin directory to /usr/local/bin , or another preferred bin directory in your $PATH .
    5. +
  5. Move the contents of the /lib directory to /usr/local/lib (or elsewhere in your $PATH).
    6. +
  6. So too with the contents of the include directory, move them to /usr/local/include (or elsewhere).
    7. +
  7. This can optionally be repeated with the share directory as well.
    8. +
+
+

Make sure the location you placed the binary files is in your $PATH environment +variable. Finally, add an environment variable that states $HDF5_ROOT = +/usr/local/lib (or your favorite other location).

+
+
+

Teuchos

+

Download the Trilinos source code to some location such as ~/trilinos_source .

+

If CMake fails to find your c, cxx, or fortran compilers, double check that +these are in your path. You may also inform CMake of your default compilers +with environment variables that CMake pays attention to. To set the C compiler, +for example, you would set the $CC environmet variable to /usr/bin/gcc-3 .

+

Running cmake:

+
cd ~/trilinos_source
+cd ../
+mkdir trilinos_build
+cd trilinos_bild
+cmake-gui ../trilinos_source
+
+

From the gui (or via commandline flags, if you prefer), set the following +advanced configuration flags for the Trilinos build:

+
+
    +
  • BUILD_SHARED_LIBS=ON
    • +
  • CMAKE_INSTALL_PREFIX=/usr/local/ (or elsewhere)
    • +
  • Trilinos_ENABLE_TEUCHOS=ON
    • +
  • BLAS_LIBRARY_DIRS=/usr/lib
    • +
  • LAPACK_LIBRARY_DIRS=/usr/lib
    • +
  • BLAS_LIBRARY_NAMES=”blas”
    • +
  • LAPACK_LIBRARY_NAMES=”lapack”
    • +
+
+

Finally, configure and generate the make file (in the gui, these are buttons). +In the terminal type make, then type make install.

+
+
+

Now What?

+

You’re now ready to build cyclus. Onward to GettingAndBuildingCyclus.

+
+
+ + +
+
+
+
+
+
+

Navigation

+ +
+
+ © Copyright 2012, Robert Carlsen. + Created using Sphinx 1.1.2. +
+ + \ No newline at end of file diff --git a/basics/get_and_build.html b/basics/get_and_build.html index 56deebfd6..80ef14fba 100644 --- a/basics/get_and_build.html +++ b/basics/get_and_build.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Getting and Building Cyclus — Cyclus + Getting and Building Cyclus — Cyclus Home @@ -25,12 +26,17 @@ - + - + +
+ +
+ +

Navigation

-

Table Of Contents

Project Repository

@@ -272,12 +287,12 @@

Navigation

index
  • - next |
  • previous |
    • -
  • Cyclus »
    • +
  • Cyclus Home »
  • Cyclus Fundamentals »
    • diff --git a/basics/introduction.html b/basics/introduction.html index 1373e2115..977ec9bb9 100644 --- a/basics/introduction.html +++ b/basics/introduction.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Introduction to the Cyclus Fuel Cycle Simulator — Cyclus + Introduction to the Cyclus Fuel Cycle Simulator — Cyclus Home @@ -25,12 +26,17 @@ - + +
    + +
    + +

    Navigation

    -

    Table Of Contents

    diff --git a/basics/main.html b/basics/main.html index ea73483d3..a990c8201 100644 --- a/basics/main.html +++ b/basics/main.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Cyclus Fundamentals — Cyclus + Cyclus Fundamentals — Cyclus Home @@ -25,11 +26,16 @@ - + +
    + +
    + +

    Navigation

    -

    Previous topic

    Cyclus

    Next topic

    Introduction to the Cyclus Fuel Cycle Simulator

    -

    This Page

    -
    diff --git a/basics/style_guide.html b/basics/style_guide.html new file mode 100644 index 000000000..d73f2f086 --- /dev/null +++ b/basics/style_guide.html @@ -0,0 +1,181 @@ + + + + + + + + + + + Style Guidelines for Developers — Cyclus Home + + + + + + + + + + + + + + +
    + +
    + + +
    +

    Navigation

    + +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Getting and Building Cyclus

    +

    Next topic

    +

    Radioactive Decay in Cyclus

    + + +
    +
    + +
    +
    +
    +
    + +
    +

    Style Guidelines for Developers

    +

    The purpose of this page is to introduce some general style guidelines to help +with readability, maintainability and extensibility of the cyclus code base.

    +
    +

    Class File Organization

    +

    Class header files should be organized in the following order:

    +
    +
      +
    • private
        +
      • methods
          +
        • virtual
          • +
        • static
          • +
        • non-static
          • +
        +
        • +
      • data members
          +
        • static
          • +
        • non-static
          • +
        +
        • +
      +
      • +
    • protected (in same order as above)
      • +
    • public (in same order as above)
      • +
    +
    +

    Within each section, methods should be grouped and ordered in logical +categories in the following order:

    +
    +
      +
    • “life-cycle” methods first (e.g. constructors, destructors, initializers)
      • +
    • operators (e.g. equivalence, assignment)
      • +
    • data access methods
      • +
    • other base-class-specific categories
      • +
    • other class-specific categories
      • +
    +
    +

    The order of method definition in the implementation file should be consistent +with the order of declaration in the header file.

    +
    +
    +

    Code Formatting

    +

    Line lengths, tab spacing, and bracket placement will conform to the google c++ +style standard as much as possible. This requires that all tabs be replaced by +spaces, and that an indentation is equal to two spaces. Further information on +this style standard can be found in the Google Style Guide.

    +

    Notable items:

    +
    +
      +
    • no tabs - expand all tabs to 2 spaces.
      • +
    • enum items should be all caps
      • +
    • trailing underscores must be used with all class member variables
      • +
    • opening braces should be placed on the same line as function args: ReturnType functionName(Arg1Type arg_name) {
      • +
    • loop and branching statements should use the opening and closing braces (i.e. not like this: if (true) long_statement;)
      • +
    +
    +
    +
    + + +
    +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2012, Robert Carlsen. + Created using Sphinx 1.1.2. +
    + + \ No newline at end of file diff --git a/devdoc/CyclusStyleGuidelines.html b/devdoc/CyclusStyleGuidelines.html index 99552667e..3549b9012 100644 --- a/devdoc/CyclusStyleGuidelines.html +++ b/devdoc/CyclusStyleGuidelines.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Cyclus Style Guidelines — Cyclus + Cyclus Style Guidelines — Cyclus Home @@ -25,12 +26,17 @@ - + - + +
    + +
    + +

    Navigation

    -

    Table Of Contents

    diff --git a/devdoc/flow_and_structure.html b/devdoc/flow_and_structure.html new file mode 100644 index 000000000..1db1e44e1 --- /dev/null +++ b/devdoc/flow_and_structure.html @@ -0,0 +1,298 @@ + + + + + + + + + + + Program Flow and Data Structures — Cyclus Home + + + + + + + + + + + + + + +
    + +
    + + +
    +

    Navigation

    + +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Developing Market Models

    +

    Next topic

    +

    Output Database

    + + +
    +
    + +
    +
    +
    +
    + +
    +

    Program Flow and Data Structures

    +
    +

    Program Flow Overview

    +

    Execution flow outline:

    +
    +
      +
    1. Read input
      2. +
    2. Setup model
      3. +
    3. Start time steps
      4. +
    +
    +
    +
    +
    +
    +

    Simulation Initialization

    +
    +
      +
    1. Load markets based on market models
      2. +
    +
    +
      +
    1. for each market
      2. +
    +
    +
      +
    1. check whether the model for this market has been loaded already, and load if necessary
      2. +
    2. instantiate new market and initialize parameters
      3. +
    +
    +
      +
    1. Assign commodities to markets
      2. +
    +
    +
    +
    +
      +
    1. Load facilities based on facility models
      2. +
    +
    +
      +
    1. for each facility
      2. +
    +
    +
      +
    1. check whether the model for this facility has been loaded already, and load if necessary
      2. +
    2. instantiate a template for a new facility based on input parameters
        +
      1. assign commodities to facilities and cross-reference with markets
        2. +
      +
      3. +
    3. add template to facility template map
      4. +
    +
    +
    +
      +
    1. Load regions based on region models
      2. +
    +
    +
      +
    1. for each region
      2. +
    +
    +
      +
    1. check whether the model for this region has been loaded already, and load if necessary
      2. +
    2. instantiate new region and initialize parameters
      3. +
    3. create list of available facility templates for that region
      4. +
    +
    +
    +
      +
    1. Load simulation parameters
      2. +
    +
    +
    +
    +

    Facility Deployment

    +

    When and how does facility deployment happen, based on the list of facility +templates?

    +
    +
    +

    The Tick

    +
    +
    +
    # cycle through Regions
    +
    +
    # cycle through Institutions
    +

    # deploy new facilities as necessary +# cycle through facilities

    +
    +
    # update facility state as appropriate +# prompt for requests/offers
    +
    +
    +
    +
    +
    +
    +
    +

    Market Resolution

    +
    +
      +
    • convert sets of requests/offers into sets of material transactions
      • +
    +
    +
    +
    +

    The Tock

    +
    +
      +
    1. cycle through Markets
      2. +
    +
    +
      +
    1. cycle through transactions
      2. +
    +
    +
      +
    1. preform material transactions
      2. +
    2. update facility state as appropriate
      3. +
    +
    +
    +
    +
    +
    +
    +

    Data Structure Overview

    +
    +

    Abstract Base Classes

    +
    +

    Communicator

    +

    Provides all functionality for message passing among facilities and markets, +including offers/requests and transactions.

    +
    +
    +

    Facility

    +

    Provides base definition of facility and standard interface. All derived +classes must implement this interface cleanly so that they can operate as +plug-in modules.

    +
    +
    +

    Market

    +

    Provides base definition of a market and standard interface. All derived +classes must implement this interface cleanly so that they can operate as +plug-in modules.

    +
    +
    +

    Region

    +

    Provides base definition of a region and standard interface. All derived +classes must implement this interface cleanly so that they can operate as +plug-in modules.

    +
    +
    +
    +
    + + +
    +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2012, Robert Carlsen. + Created using Sphinx 1.1.2. +
    + + \ No newline at end of file diff --git a/devdoc/main.html b/devdoc/main.html index 43dc4b382..ecc4b8d50 100644 --- a/devdoc/main.html +++ b/devdoc/main.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Cyclus Developer Guide — Cyclus + Cyclus Developer Guide — Cyclus Home @@ -25,11 +26,16 @@ - - + + +
    + +
    + +

    Navigation

    -

    Table Of Contents

    diff --git a/devdoc/make-models/facility.html b/devdoc/make-models/facility.html new file mode 100644 index 000000000..63ab218ff --- /dev/null +++ b/devdoc/make-models/facility.html @@ -0,0 +1,150 @@ + + + + + + + + + + + Developing Region Models — Cyclus Home + + + + + + + + + + + + + + +
    + +
    + + +
    +

    Navigation

    + +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Developing Models For Cyclus

    +

    Next topic

    +

    Developing Institution Models

    + + +
    +
    + +
    +
    +
    +
    + +
    +

    Developing Region Models

    +

    After reading GuidelinesForImplementingNewModels, this should provide +additional information specific to implementing a new FacilityModel.

    +
    +

    Details

    +

    In addition to inheriting from the main dynamic loading base class Model, all +FacilityModel models also inherit from Communicator.

    +

    A FacilityModel is one of the primary actors in the Cyclus system. All +offers and requests originate at an instance of a FacilityModel and all +shipments are executed by an instance of a FacilityModel.

    +

    While running, Cyclus will use a FacilityModel in two ways. First, it will +read user input to define a template instance of a FacilityModel. A choice of +a FacilityModel model combined with some distinct set of parameters for that +model results in a facility that is available for deployment by an InstModel +institution if allowed by that institution’s RegionModel region. Second, +Cyclus will create copies of the FacilityModel facilities as they are +deployed by the institutions. For this reason, the FacilityModel class defines +a data member fac_name that is the name of the individual deployed facility.

    +

    All FacilityModel models should know which set of Commodity objects they trade +and/or which MarketModel markets they participate in. Each FacilityModel model +should implement a method named sendMessages to generate offer and request +messages to send to their markets and methods named sendMaterial and +receiveMaterial to process shipment messages that originate with their +markets.

    +
    +
    + + +
    +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2012, Robert Carlsen. + Created using Sphinx 1.1.2. +
    + + \ No newline at end of file diff --git a/devdoc/make-models/institution.html b/devdoc/make-models/institution.html index a604be9ba..96483df04 100644 --- a/devdoc/make-models/institution.html +++ b/devdoc/make-models/institution.html @@ -1,5 +1,6 @@ + @@ -8,7 +9,7 @@ - Developing Institution Models — Cyclus + Developing Institution Models — Cyclus Home @@ -25,12 +26,17 @@ - + - - + + +
    + +
    + +

    Navigation

    - +

    Table Of Contents

    + +

    Previous topic

    -

    Developing Models For Cyclus

    +

    Developing Region Models

    Next topic

    -

    Developing Market Models

    -

    This Page

    - +

    Developing Region Models