diff --git a/extra/function/LICENSE b/extra/function/LICENSE new file mode 100644 index 00000000..f288702d --- /dev/null +++ b/extra/function/LICENSE @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/extra/function/README.md b/extra/function/README.md new file mode 100644 index 00000000..b8fa074d --- /dev/null +++ b/extra/function/README.md @@ -0,0 +1 @@ +# Analytical function solver module for Py2DMAT diff --git a/extra/function/doc/.gitignore b/extra/function/doc/.gitignore new file mode 100644 index 00000000..c795b054 --- /dev/null +++ b/extra/function/doc/.gitignore @@ -0,0 +1 @@ +build \ No newline at end of file diff --git a/extra/function/doc/common/img/himmelblau_mapper.pdf b/extra/function/doc/common/img/himmelblau_mapper.pdf new file mode 100644 index 00000000..a950d0b9 Binary files /dev/null and b/extra/function/doc/common/img/himmelblau_mapper.pdf differ diff --git a/extra/function/doc/common/img/himmelblau_mapper.png b/extra/function/doc/common/img/himmelblau_mapper.png new file mode 100644 index 00000000..461c6cd3 Binary files /dev/null and b/extra/function/doc/common/img/himmelblau_mapper.png differ diff --git a/extra/function/doc/en/Makefile b/extra/function/doc/en/Makefile new file mode 100644 index 00000000..ed7c6d24 --- /dev/null +++ b/extra/function/doc/en/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = pyMC +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W $(SPHINXOPTS) $(O) diff --git a/extra/function/doc/en/make.bat b/extra/function/doc/en/make.bat new file mode 100644 index 00000000..36108d30 --- /dev/null +++ b/extra/function/doc/en/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=python -msphinx +) +set SOURCEDIR=source +set BUILDDIR=build +set SPHINXPROJ=pyMC + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% -W %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/extra/function/doc/en/source/acknowledgement.rst b/extra/function/doc/en/source/acknowledgement.rst new file mode 100644 index 00000000..5db6b52f --- /dev/null +++ b/extra/function/doc/en/source/acknowledgement.rst @@ -0,0 +1,6 @@ +*************************** +Acknowledgements +*************************** + +The development of 2DMAT was supported by JSPS KAKENHI Grant Number 19H04125 "Unification of computational statistics and measurement technology by massively parallel machine" +and "Project for advancement of software usability in materials science" (fiscal year 2020, 2021, 2024) of The Institute for Solid State Physics, The University of Tokyo. diff --git a/extra/function/doc/en/source/conf.py b/extra/function/doc/en/source/conf.py new file mode 100644 index 00000000..18a0da38 --- /dev/null +++ b/extra/function/doc/en/source/conf.py @@ -0,0 +1,190 @@ +# -*- coding: utf-8 -*- +# +# MateriApps-Installer documentation build configuration file, created by +# sphinx-quickstart on Sun May 1 14:29:22 2020. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.mathjax'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'2DMAT solver module: Functions' +copyright = u'2020, Institute for Solid State Physics, University of Tokyo' +author = u'2DMAT Developer team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'1.0' +# The full version, including alpha/beta/rc tags. +release = u'1.0-dev' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'haiku' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + # 'font_family': 'Helvetica', + # 'sidebar_search_button': 'pink_1' +} + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +numfig = True + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = '2DMATdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +# latex_engine = 'uplatex' + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'userguide_functions.tex', u'2DMAT Functions Documentation', + author, 'manual', 'True'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, '2dmat-functions', u'2DMAT Documentation', + [author], 1) +] + +#latex_docclass = {'manual': 'jsbook'} + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, '2dmat-functions', u'2DMAT Documentation', + author, '2DMAT', 'One line description of project.', + 'Miscellaneous'), +] + +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + + + diff --git a/extra/function/doc/en/source/contact.rst b/extra/function/doc/en/source/contact.rst new file mode 100644 index 00000000..b27117bf --- /dev/null +++ b/extra/function/doc/en/source/contact.rst @@ -0,0 +1,22 @@ +Contact +========================================= + +- Bug Reports + + Please report all problems and bugs on the github `Issues `_ page. + + To resolve bugs early, follow these guidelines when reporting: + + 1. Please specify the version of 2DMAT and 2DMAT-Functions you are using. + + 2. If there are problems for installation, please inform us about your operating system and the compiler. + + 3. If a problem occurs during execution, enter the input file used for execution and its output. + + Thank you for your cooperation. + +- Others + + If you have any questions about your research that are difficult to consult at Issues on GitHub, please send an e-mail to the following address: + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (replace _at_ by @) diff --git a/extra/function/doc/en/source/index.rst b/extra/function/doc/en/source/index.rst new file mode 100644 index 00000000..47a80e4c --- /dev/null +++ b/extra/function/doc/en/source/index.rst @@ -0,0 +1,26 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to 2DMAT's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + install + tutorial/index + solver + acknowledgement + contact + +.. + input + output + algorithm/index + solver/index + tool + customize/index diff --git a/extra/function/doc/en/source/install.rst b/extra/function/doc/en/source/install.rst new file mode 100644 index 00000000..56ec6014 --- /dev/null +++ b/extra/function/doc/en/source/install.rst @@ -0,0 +1,75 @@ +Installation of 2DMAT-Functions +================================================================ + +Prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Python3 (>=3.6.8) + + - The following Python packages are required. + + - tomli >= 1.2 + - numpy >= 1.14 + +- py2dmat version 3.0 and later + + +How to download and install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Install py2dmat + + - From source files: + + Download source files of py2dmat from the repository as follows: + + .. code-block:: bash + + $ git clone -b update https://github.com/issp-center-dev/2DMAT.git + + Install py2dmat using ``pip`` command: + + .. code-block:: bash + + $ cd 2DMAT + $ python3 -m pip install . + + You may add ``--user`` option to install py2dmat locally (in ``$HOME/.local``). + + If you run the following command instead, optional packages will also be installed at the same time. + + .. code-block:: bash + + $ python3 -m pip install .[all] + +2. Install py2dmat-function + + - From source files: + + At present, the source files of 2dmat-functions are placed in ``extra`` directory of py2dmat source package. After obtaining the source files following the step 1, install 2dmat-functions using ``pip`` command as follows: + + .. code-block:: bash + + $ cd 2DMAT/extra/function + $ python3 -m pip install . + + You may add ``--user`` option to install the package locally (in ``$HOME/.local``). + + Then, the library of 2DMAT-Functions wil be installed. + + +How to run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In 2DMAT, the analysis is done by using a predefined optimization algorithm and a direct problem solver. +The ways to do analyses of Functions is to write a program for the analysis with 2DMAT-Functions library and 2DMAT framework. +The type of the inverse problem algorithms can be chosen by importing the appropriate module. +A flexible use would be possible, for example, to include data generation within the program. +The types of parameters and the instruction to use the library will be given in the subsequent sections. + + +How to uninstall +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In order to uninstall 2DMAT-Functions and 2DMAT modules, type the following commands: + +.. code-block:: bash + + $ python3 -m pip uninstall py2dmat-function py2dmat diff --git a/extra/function/doc/en/source/introduction.rst b/extra/function/doc/en/source/introduction.rst new file mode 100644 index 00000000..c5c6e564 --- /dev/null +++ b/extra/function/doc/en/source/introduction.rst @@ -0,0 +1,91 @@ +Introduction +================================ + +What is 2DMAT ? +-------------------------------- + +2DMAT is a framework for applying a search algorithm to a direct problem solver to find the optimal solution. +As the standard direct problem solver, the experimental data analysis software for two-dimensional material structure analysis is prepared. +The direct problem solver gives the deviation between the experimental data and the calculated data obtained under the given parameters such as atomic positions as a loss function used in the inverse problem. +The optimal parameters are estimated by minimizing the loss function using a search algorithm. For further use, the original direct problem solver or the search algorithm can be defined by users. +In the current version, for solving a direct problem, 2DMAT offers the wrapper of the solver for the total-reflection high-energy positron diffraction (TRHEPD), the surface X-ray diffraction (Functions), and the low-energy electron diffraction (LEED). +As algorithms, it offers the Nelder-Mead method, the grid search method, the Bayesian optimization method, the replica exchange Monte Carlo method, and the population annealing Monte Carlo method. + + +What is 2DMAT-Functions ? +-------------------------------- + +``2DMAT-Functions`` provides implementation of several analytical functions for the direct problems of 2DMAT. +The major use of this module is to test and benchmark the optimization algorithms of 2DMAT, while it may be useful as a template when the users write their own direct problem solvers. + +It was originally developed as a component of 2DMAT v2.x, and has been restructured as a separate module to be used with 2DMAT. + + + +License +-------------------------------- +| This package is distributed under GNU General Public License version 3 (GPL v3). + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +This software was developed with the support of "Project for advancement of software usability in materials science" of The Institute for Solid State Physics, The University of Tokyo. +We hope that you cite the following reference when you publish the results using 2DMAT: + +"Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures", Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, `Computer Physics Communications 280, 108465 (2022). `_ + +Bibtex: + +| @article{MOTOYAMA2022108465, +| title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures}, +| journal = {Computer Physics Communications}, +| volume = {280}, +| pages = {108465}, +| year = {2022}, +| issn = {0010-4655}, +| doi = {https://doi.org/10.1016/j.cpc.2022.108465}, +| url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849}, +| author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi} +| } + + +Version Information +-------------------------------- + +2DMAT-Functions + +- v1.0.0: 2024-XX-XX + +2DMAT + +- v3.0.0: 2024-XX-XX +- v2.1.0: 2022-04-08 +- v2.0.0: 2022-01-17 +- v1.0.1: 2021-04-15 +- v1.0.0: 2021-03-12 +- v0.1.0: 2021-02-08 + + +Main developers +-------------------------------- + +2DMAT has been developed by following members. + +- v3.0.0 - + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - T. Aoyama (The Institute for Solid State Physics, The University of Tokyo) + - T. Hoshi (National Institute for Fusion Science) + +- v2.0.0 - + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - H. Iwamoto (Department of Applied Mathematics and Physics, Tottori University) + - T. Hoshi (Department of Applied Mathematics and Physics, Tottori University) + +- v0.1.0 - v1.0.1 + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - T. Hoshi (Department of Applied Mathematics and Physics, Tottori University) diff --git a/extra/function/doc/en/source/solver.rst b/extra/function/doc/en/source/solver.rst new file mode 100644 index 00000000..aa764619 --- /dev/null +++ b/extra/function/doc/en/source/solver.rst @@ -0,0 +1,47 @@ +Predefined functions +================================ + +``2DMAT-Functions`` module provides ``Solver`` that computes a predefined benchmark function :math:`f(x)` for evaluating the performance of search algorithms. + +Each function is implemented as a class that can be used for a direct solver of 2DMAT. +The predefined functions are listed as follows. + +- ``Quadratics`` + + - Quadratic function + + .. math:: + + f(\vec{x}) = \sum_{i=1}^N x_i^2 + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Rosenbrock`` + + - `Rosenbrock function `_ + + .. math:: + + f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right] + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)` + +- ``Ackley`` + + - `Ackley function `_ + + .. math:: + + f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right] + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Himmerblau`` + + - `Himmerblau function `_ + + .. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + + - The optimized value :math:`f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0` diff --git a/extra/function/doc/en/source/tutorial/booth.rst b/extra/function/doc/en/source/tutorial/booth.rst new file mode 100644 index 00000000..35f5dc10 --- /dev/null +++ b/extra/function/doc/en/source/tutorial/booth.rst @@ -0,0 +1,196 @@ +Adding functions +================================ + +In this tutorial, we describe the procedure how to define a new function and perform analyses. +As an example, we will introduce Booth function given below: + +.. math:: + + f(x,y) = (x + 2 y - 7) ^2 + (2 x + y - 5) ^2 + +The minimum value of this function is :math:`f(1,3) = 0`. + + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/booth``. +The following files are stored in the folder. + +- ``booth.py`` + + Source file of the direct problem solver that evaluates Booth function. + +- ``main.py`` + + Source file of the main program. This program reads ``input.toml`` for the parameters. + +- ``input.toml`` + + Input parameter file for ``main.py``. + +- ``do.sh`` + + Script file for running this tutorial. + +The following sections describe these files and then show the actual calculation results. + + +Description of main program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ``booth.py``, a class for the direct problem solver is defined using 2DMAT-Functions module that evaluates Booth function. +The entire program is shown as follows: + +.. code-block:: python + + import numpy as np + import py2dmat.extra.function + + class Booth(py2dmat.extra.function.Solver): + def evaluate(self, xs: np.ndarray, args=()): + assert xs.shape[0] == 2 + x, y = xs + fx = (x + 2 * y - 7)**2 + (2 * x + y - 5)**2 + return fx + +First, the required modules are imported. +``py2dmat.extra.function`` corresponds to 2DMAT-Functions module. + +Next, ``Booth`` class is defined as derived from ``Solver`` class of 2DMAT-Functions. +The direct problem solver class must have a method called ``evaluate`` which have the form ``evaluate(self, xs, args) -> float``. +The arguments of this method are: +``xs`` of ``numpy.ndarray`` type for the parameter values, and ``args`` of ``Tuple`` type for the optional data that consists of the step count ``step`` and the iteration count ``set`` used in the class accordingly. + +``main.py`` is a simple program that performs analyses using the Booth class. + +.. code-block:: python + + import numpy as np + + import py2dmat + import py2dmat.algorithm.min_search as min_search + from booth import Booth + + info = py2dmat.Info.from_file("input.toml") + solver = Booth(info) + runner = py2dmat.Runner(solver, info) + + alg = min_search.Algorithm(info, runner) + alg.main() + + +In the program, the instances of the classes are created. + +- ``py2dmat.Info`` class + + This class is for storing the parameters. + An instance is created by calling a class method ``from_file`` with a path to TOML file as an argument. + +- ``Booth`` class + + Booth class is imported from ``booth.py`` as introduced above, and is instantiated. + +- ``py2dmat.Runner`` class + + This class is for connecting the direct problem solver and the inverse problem algorithm. + An instance is created by passing an instance of Solver class and an instance of Info class. + +- ``py2dmat.algorithm.min_search.Algorithm`` class + + This class is for the inverse problem algorithm. + In this tutorial, we use ``min_search`` module that implements the optimization by Nelder-Mead method. + An instance is created by passing an instance of Runner class. + +After creating the instances of Solver, Runner, and Algorithm in this order, we invoke ``main()`` method of the Algorithm class to start analyses. + + +Input files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An example of the input parameter file ``input.toml`` is shown below. + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + + [solver] + + [runner] + [runner.log] + interval = 20 + + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located. + +.. code-block:: + + $ cd sample/booth + +Run the main program. The computation time will take only a few seconds on a normal PC. + +.. code-block:: + + $ python3 main.py | tee log.txt + +The standard output will look as follows. + +.. code-block:: + + Optimization terminated successfully. + Current function value: 0.000000 + Iterations: 44 + Function evaluations: 82 + iteration: 44 + len(allvecs): 45 + step: 0 + allvecs[step]: [ 5.15539311 -2.20349335] + step: 1 + allvecs[step]: [ 4.65539311 -1.82849335] + step: 2 + allvecs[step]: [ 4.40539311 -1.26599335] + step: 3 + allvecs[step]: [ 3.28039311 -0.73474335] + step: 4 + allvecs[step]: [2.21789311 0.65588165] + step: 5 + allvecs[step]: [2.21789311 0.65588165] + ... + step: 42 + allvecs[step]: [0.99997645 3.00001226] + step: 43 + allvecs[step]: [0.99997645 3.00001226] + end of run + Current function value: 1.2142360244883376e-09 + Iterations: 44 + Function evaluations: 82 + Solution: + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + +``x1`` and ``x2`` are the candidate parameters at each step. +The final estimated parameters will be written in ``output/res.dat``. +In the current case, the following result will be obtained: + +.. code-block:: + + fx = 1.2142360244883376e-09 + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + +It is found that the minimum has been reproduced. + +Note that ``do.sh`` is available as a script for batch calculation. diff --git a/extra/function/doc/en/source/tutorial/himmelblau.rst b/extra/function/doc/en/source/tutorial/himmelblau.rst new file mode 100644 index 00000000..d44573d2 --- /dev/null +++ b/extra/function/doc/en/source/tutorial/himmelblau.rst @@ -0,0 +1,163 @@ +Minimization of Himmelblau function +================================================================ + +In this tutorial, we will write a user program using 2DMAT-Functions module and perform analyese. As an example, we adopt the Nelder-Mead method for the inverse problem algorithm. + + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/himmelblau``. +The following files are stored in the folder. + +- ``main.py`` + + Source file of the main program. This program reads ``input.toml`` for the parameters. + +- ``input.toml`` + + Input parameter file for ``main.py``. + +- ``do.sh`` + + Script file for running this tutorial. + +- ``plot_colormap_2d.py`` + + Program for visualizing the results. + +The following sections describe these files and then show the actual calculation results. + + +Description of main program +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``main.py`` is a simple program for the analyses using 2DMAT-Functions module. +The entire source file is shown as follows: + +.. code-block:: python + + import numpy as np + + import py2dmat + import py2dmat.algorithm.mapper_mpi as mapper + from py2dmat.extra.function import Himmelblau + + info = py2dmat.Info.from_file("input.toml") + solver = Himmelblau(info) + runner = py2dmat.Runner(solver, info) + + alg = mapper.Algorithm(info, runner) + alg.main() + + +At the beginning of the program, the required modules are imported as listed below. + +- ``py2dmat`` for the main module of 2DMAT. + +- ``py2dmat.algorithm.mapper_mpi`` for the module of the inverse problem algorithm. + +- ``Himmelblau`` class from ``py2dmat.extra.function`` module. + +Next, the instances of the classes are created. + +- ``py2dmat.Info`` class + + This class is for storing the parameters. + An instance is created by calling a class method ``from_file`` with a path to TOML file as an argument. + +- ``Himmelblau`` class + + This class is for the Himmelblau function defined in the 2DMAT-Functions module. + An instance is created by passing an instance of Info class. + +- ``py2dmat.Runner`` class + + This class is for connecting the direct problem solver and the inverse problem algorithm. + An instance is created by passing an instance of Solver class and an instance of Info class. + +- ``py2dmat.algorithm.min_search.Algorithm`` class + + This class is for the inverse problem algorithm. + In this tutorial, we use ``min_search`` module that implements the optimization by Nelder-Mead method. + An instance is created by passing an instance of Runner class. + +After creating the instances of Solver, Runner, and Algorithm in this order, we invoke ``main()`` method of the Algorithm class to start analyses. + + +Input files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An example of the input parameter file ``input.toml`` is shown below. +Except, ``algorithm.name`` parameter for specifying the algorithm type should be ignored. + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + + [solver] + + [runner] + [runner.log] + interval = 20 + + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located. (We assume that you are directly under the directory where you downloaded this software.) + +.. code-block:: + + $ cd sample/himmelblau + +Run the main program. The computation time will take only a few seconds on a normal PC. + +.. code-block:: + + $ mpiexec -np 4 python3 main.py + +In the above, the main program is executed with 4 MPI parallel processes. +The standard output will look as follows. + +.. code-block:: + + Make ColorMap + Iteration : 1/240 + Iteration : 2/240 + Iteration : 3/240 + Iteration : 4/240 + Iteration : 5/240 + Iteration : 6/240 + Iteration : 7/240 + Iteration : 8/240 + Iteration : 9/240 + Iteration : 10/240 + ... + + +Visualization of results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By plotting ``output/ColorMap.txt``, you can identify the region of parameters in which the function yield small values. +A program to draw such a two-dimensional plot is prepared in ``plot_colormap_2d.py``. + +.. code-block:: + + $ python3 plot_colormap_2d.py + +By typing as above, ``ColorMapFig.png`` is generated in which a color map of the function values evaluated at the grid, on top of the contour of Himmelblau function. + +.. figure:: ../../../common/img/himmelblau_mapper.* + + A color map of the function values in the two-dimensional parameter space. diff --git a/extra/function/doc/en/source/tutorial/index.rst b/extra/function/doc/en/source/tutorial/index.rst new file mode 100644 index 00000000..dbdb9439 --- /dev/null +++ b/extra/function/doc/en/source/tutorial/index.rst @@ -0,0 +1,18 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Tutorials +================================ + +In this tutorial, we will instruct how to use 2DMAT and 2DMAT-Functions modules, considering the minimization problem of Himmelblau function as an example. + +For the inverse problem algorithm we adopt the grid search provided as ``mapper`` module. See the 2DMAT manual for other algorithms. + + +.. toctree:: + :maxdepth: 1 + + himmelblau + booth diff --git a/extra/function/doc/ja/Makefile b/extra/function/doc/ja/Makefile new file mode 100644 index 00000000..f86728d9 --- /dev/null +++ b/extra/function/doc/ja/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W $(SPHINXOPTS) $(O) diff --git a/extra/function/doc/ja/make.bat b/extra/function/doc/ja/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/extra/function/doc/ja/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/extra/function/doc/ja/source/acknowledgement.rst b/extra/function/doc/ja/source/acknowledgement.rst new file mode 100644 index 00000000..9be001c2 --- /dev/null +++ b/extra/function/doc/ja/source/acknowledgement.rst @@ -0,0 +1,4 @@ +謝辞 +========================================= + +本ソフトウェアは、科研費(2019-2021年度)「超並列マシンを用いた計算統計と測定技術の融合」および東京大学物性研究所 ソフトウェア高度化プロジェクト (2020, 2021, 2024 年度) の支援を受け開発されました。 diff --git a/extra/function/doc/ja/source/conf.py b/extra/function/doc/ja/source/conf.py new file mode 100644 index 00000000..a9aae86c --- /dev/null +++ b/extra/function/doc/ja/source/conf.py @@ -0,0 +1,141 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = '2DMAT solver module: functions' +copyright = '2020-, 2DMAT developers' +author = '2DMAT developers' + +version = '1.0' +# The full version, including alpha/beta/rc tags +release = '1.0-dev' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.mathjax' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The master toctree document. +master_doc = 'index' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'haiku' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { +} + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'ja' + +# -- Options for LaTeX output --------------------------------------------- + +latex_engine = 'uplatex' + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'userguide_functions_ja.tex', u'2DMAT Function Module Documentation', + u'University of Tokyo', 'manual', 'True'), +] + +# latex_docclass = {'manual': 'jsbook'} + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, '2dmat', u'2DMAT Documentation', + author, '2DMAT', 'One line description of project.', + 'Miscellaneous'), +] + + +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + diff --git a/extra/function/doc/ja/source/contact.rst b/extra/function/doc/ja/source/contact.rst new file mode 100644 index 00000000..0c714e18 --- /dev/null +++ b/extra/function/doc/ja/source/contact.rst @@ -0,0 +1,22 @@ +お問い合わせ +========================================= + +2DMAT-Functions に関するお問い合わせはこちらにお寄せください。 + +- バグ報告 + + 2DMAT-Functions のバグ関連の報告は `GitHubのIssues `_ で受け付けています。 + + バグを早期に解決するため、報告時には次のガイドラインに従ってください。 + + - 使用している 2DMAT-Functions のバージョンを指定してください。 + + - インストールに問題がある場合には、使用しているオペレーティングシステムとコンパイラの情報についてお知らせください。 + + - 実行に問題が生じた場合は、実行に使用した入力ファイルとその出力を記載してください。 + +- その他 + + 研究に関連するトピックなどGitHubのIssuesで相談しづらいことを問い合わせる際には、以下の連絡先にコンタクトをしてください。 + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (_at_を@に変更してください) diff --git a/extra/function/doc/ja/source/index.rst b/extra/function/doc/ja/source/index.rst new file mode 100644 index 00000000..7beaecce --- /dev/null +++ b/extra/function/doc/ja/source/index.rst @@ -0,0 +1,23 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to 2DMAT's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + install + tutorial/index + solver + acknowledgement + contact +.. + usage + input + output + examples diff --git a/extra/function/doc/ja/source/install.rst b/extra/function/doc/ja/source/install.rst new file mode 100644 index 00000000..db98d362 --- /dev/null +++ b/extra/function/doc/ja/source/install.rst @@ -0,0 +1,72 @@ +インストール +================================================================ + +実行環境・必要なパッケージ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- python 3.6.8 以上 + + - 必要なpythonパッケージ + + - tomli (>= 1.2) + - numpy (>= 1.14) + +- py2dmat version 3.0 以降 + + +ダウンロード・インストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. py2dmat をインストールする + + - ソースコードからのインストール + + リポジトリから py2dmat のソースファイルを取得します。 + + .. code-block:: bash + + $ git clone -b update https://github.com/issp-center-dev/2DMAT.git + + pip コマンドを実行してインストールします。 + + .. code-block:: bash + + $ cd 2DMAT + $ python3 -m pip install . + + + ``--user`` オプションを付けるとローカル (``$HOME/.local``) にインストールできます。 + + ``python3 -m pip install .[all]`` を実行するとオプションのパッケージも同時にインストールします。 + +2. py2dmat-functions をインストールする + + - ソースコードからのインストール + + py2dmat-functions のソースファイルは、現在は py2dmat のソースパッケージの extra ディレクトリ内に配置されています。1. に記述した手順に従って py2dmat のソースファイルを取得した後、 ``extra/function`` ディレクトリ内で pip コマンドを実行してインストールします。 + + .. code-block:: bash + + $ cd 2DMAT/extra/function + $ python3 -m pip install . + + ``--user`` オプションを付けるとローカル (``$HOME/.local``) にインストールできます。 + + 2DMAT-Functions のライブラリがインストールされます。 + + +実行方法 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2DMAT では順問題ソルバと逆問題解析アルゴリズムを組み合わせて解析を行います。 +2DMAT-Functions に用意された関数の最適化問題の解析を行うには、2DMAT-Functions ライブラリと 2DMAT フレームワークを用いてプログラムを作成し、解析を行います。逆問題解析アルゴリズムは import するモジュールで選択します。プログラム中に入力データの生成を組み込むなど、柔軟な使い方ができます。 +ライブラリの利用方法については以降の章で説明します。 + + +アンインストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +2DMAT-Functions モジュールおよび 2DMAT モジュールをアンインストールするには、以下のコマンドを実行します。 + +.. code-block:: bash + + $ python3 -m pip uninstall py2dmat-function py2dmat diff --git a/extra/function/doc/ja/source/introduction.rst b/extra/function/doc/ja/source/introduction.rst new file mode 100644 index 00000000..6f7bf6d9 --- /dev/null +++ b/extra/function/doc/ja/source/introduction.rst @@ -0,0 +1,90 @@ +はじめに +================================ + +2DMATとは +-------------------------------- + +2DMATは、順問題ソルバーに対して探索アルゴリズムを適用して最適解を探すためのフレームワークです。 +順問題ソルバーはユーザー自身で定義できるほか、標準的な順問題ソルバーとして2次元物質構造解析向け実験データ解析ソフトウェアが用意されています。 +順問題ソルバーでは、原子位置などをパラメータとして得られたデータと実験データとのずれを損失関数として与えます。 +探索アルゴリズムによりこの損失関数を最小化する最適なパラメータを推定します。 +現バージョンでは、順問題ソルバーとして量子ビーム回折実験の全反射高速陽電子回折法(Total-Reflection High-Energy Positron Diffraction: TRHEPD), 表面X線回折法(Surface X-ray Diffraction: SXRD), 低速電子線回折法(Low Energy Electron Diffraction: LEED)に対応しており、 +探索アルゴリズムはNelder-Mead法, グリッド型探索法, ベイズ最適化, レプリカ交換モンテカルロ法, ポピュレーションアニーリングモンテカルロ法が実装されています。 + + +2DMAT-Functionsとは +-------------------------------- + +2DMAT-Functions は 2DMAT 向けの順問題として解析関数を提供するものです。主な用途は 2DMAT のテストとベンチマークですが、ユーザが独自の順問題ソルバーを作成する上で雛形としても利用できます。 + +このモジュールは 2DMAT v2.x の順問題ソルバーの一つとして開発されたコンポーネントを、独立なモジュールとして再構成したものです。2DMAT と組み合わせて使用します。 + +ライセンス +-------------------------------- +| 本ソフトウェアのプログラムパッケージおよびソースコード一式はGNU + General Public License version 3 (GPL v3) に準じて配布されています。 + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +本ソフトウェアは2020年度および2024年度 東京大学物性研究所 ソフトウェア高度化プロジェクトの支援を受け開発されました。 +2DMATを引用する際には以下の文献を引用してください。 + +"Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures", +Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, Computer Physics Communications 280, 108465 (2022). + +Bibtex: + +| @article{MOTOYAMA2022108465, +| title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures}, +| journal = {Computer Physics Communications}, +| volume = {280}, +| pages = {108465}, +| year = {2022}, +| issn = {0010-4655}, +| doi = {https://doi.org/10.1016/j.cpc.2022.108465}, +| url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849}, +| author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi} +| } + + + +バージョン履歴 +-------------------------------- + +2DMAT-Functions + +- v1.0.0 : 2024-XX-XX + +2DMAT + +- v3.0.0 : 2024-XX-XX +- v2.1.0 : 2022-04-08 +- v2.0.0 : 2022-01-17 +- v1.0.1 : 2021-04-15 +- v1.0.0 : 2021-03-12 +- v0.1.0 : 2021-02-08 + +主な開発者 +-------------------------------- + +2DMATは以下のメンバーで開発しています. + +- v3.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 青山 龍美 (東京大学 物性研究所) + - 星 健夫 (核融合科学研究所) + +- v2.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 岩本 晴道 (鳥取大学 大学院工学研究科) + - 星 健夫 (鳥取大学 大学院工学研究科) + +- v0.1.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 星 健夫 (鳥取大学 大学院工学研究科) diff --git a/extra/function/doc/ja/source/solver.rst b/extra/function/doc/ja/source/solver.rst new file mode 100644 index 00000000..68c9d6c5 --- /dev/null +++ b/extra/function/doc/ja/source/solver.rst @@ -0,0 +1,47 @@ +定義済み関数 +================================================================ + +``2DMAT-Functions`` モジュールは、探索アルゴリズムの性能評価を目的とした定義済みのベンチマーク関数 :math:`f(x)` を計算する ``Solver`` です。 + +それぞれの関数は 2DMAT の順問題ソルバーとして利用可能なクラスとして実装されています。 +定義済みの関数は以下のとおりです。 + +- ``Quadratics`` + + - 二次形式 + + .. math:: + + f(\vec{x}) = \sum_{i=1}^N x_i^2 + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Rosenbrock`` + + - `Rosenbrock 関数 `_ + + .. math:: + + f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right] + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)` + +- ``Ackley`` + + - `Ackley 関数 `_ + + .. math:: + + f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right] + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + +- ``Himmelblau`` + + - `Himmelblau 関数 `_ + + .. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + + - 最適値は :math:`f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0` diff --git a/extra/function/doc/ja/source/tutorial/booth.rst b/extra/function/doc/ja/source/tutorial/booth.rst new file mode 100644 index 00000000..a589b941 --- /dev/null +++ b/extra/function/doc/ja/source/tutorial/booth.rst @@ -0,0 +1,186 @@ +関数の追加 +================================ + +ここでは、2DMAT-Functions モジュールを用いて、ユーザが新しい関数を作成して解析を行う手順を説明します。例として次の Booth 関数 + +.. math:: + + f(x,y) = (x + 2 y - 7) ^2 + (2 x + y - 5) ^2 + +を追加してみます。この関数の最小値は :math:`f(1,3) = 0` です。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +サンプルファイルは ``sample/booth`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``booth.py`` + + Booth関数を計算する順問題ソルバーを定義する + +- ``main.py`` + + メインプログラム。パラメータを ``input.toml`` ファイルから読み込んで解析を行う + +- ``input.toml`` + + ``simple.py`` で利用する入力パラメータファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したのち、実際の計算結果を紹介します。 + + +プログラムの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``booth.py`` では、2DMAT-Functions を利用して Booth 関数を計算する順問題ソルバークラスを定義します。プログラムの全体を以下に示します。 + +.. code-block:: python + + import numpy as np + import py2dmat.extra.function + + class Booth(py2dmat.extra.function.Solver): + def evaluate(self, xs: np.ndarray, args=()): + assert xs.shape[0] == 2 + x, y = xs + fx = (x + 2 * y - 7)**2 + (2 * x + y - 5)**2 + return fx + +プログラムでは、まず必要なモジュールを import します。 +``py2dmat.extra.function`` は 2DMAT-Functions モジュールです。 + +次に、2DMAT-Functions の ``Solver`` クラスを基底クラスとして ``Booth`` クラスを作成します。 +関数値を評価するメソッドを ``evaluate(self, xs, args) -> float`` として定義します。 +``evaluate`` の引数は、パラメータ値を表す ``numpy.ndarray`` 型の引数 ``xs`` と、 ``Tuple`` 型のオプションパラメータ ``args`` です。 +``args`` はステップ数 ``step`` と n巡目を表す ``set`` からなり、必要に応じてクラス内で使用します。 + + +``main.py`` は Booth クラスを用いて解析を行うシンプルなプログラムです。 + +.. code-block:: python + + import numpy as np + + import py2dmat + import py2dmat.algorithm.min_search as min_search + from booth import Booth + + info = py2dmat.Info.from_file("input.toml") + solver = Booth(info) + runner = py2dmat.Runner(solver, info) + + alg = min_search.Algorithm(info, runner) + alg.main() + +プログラム中ではまず、解析で利用するクラスのインスタンスを作成します。 + +- ``py2dmat.Info`` クラス + + パラメータを格納するクラスです。 ``from_file`` クラスメソッドに TOML ファイルのパスを渡して作成することができます。 + +- ``Booth`` クラス + + 上記で作成した booth.py から Booth クラスを import してインスタンスを作成します。 + +- ``py2dmat.Runner`` クラス + + 順問題ソルバーと逆問題解析アルゴリズムを繋ぐクラスです。Solver クラスのインスタンスおよび Info クラスのパラメータを渡して作成します。 + +- ``py2dmat.algorithm.min_search.Algorithm`` クラス + + 逆問題解析アルゴリズムのクラスです。ここでは Nelder-Mead法による最適化アルゴリズムのクラスモジュール ``min_search`` を利用します。Runner のインスタンスを渡して作成します。 + +Solver, Runner, Algorithm の順にインスタンスを作成した後、Algorithm クラスの ``main()`` メソッドを呼んで解析を行います。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` の例を以下に示します。 + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + + [solver] + + [runner] + [runner.log] + interval = 20 + + +計算実行 +~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。 + +.. code-block:: + + $ cd sample/booth + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ python3 main.py | tee log.txt + +実行すると、以下の様な出力がされます。 + +.. code-block:: + + Optimization terminated successfully. + Current function value: 0.000000 + Iterations: 44 + Function evaluations: 82 + iteration: 44 + len(allvecs): 45 + step: 0 + allvecs[step]: [ 5.15539311 -2.20349335] + step: 1 + allvecs[step]: [ 4.65539311 -1.82849335] + step: 2 + allvecs[step]: [ 4.40539311 -1.26599335] + step: 3 + allvecs[step]: [ 3.28039311 -0.73474335] + step: 4 + allvecs[step]: [2.21789311 0.65588165] + step: 5 + allvecs[step]: [2.21789311 0.65588165] + ... + step: 42 + allvecs[step]: [0.99997645 3.00001226] + step: 43 + allvecs[step]: [0.99997645 3.00001226] + end of run + Current function value: 1.2142360244883376e-09 + Iterations: 44 + Function evaluations: 82 + Solution: + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + + +``x1``, ``x2`` に各ステップでの候補パラメータと、その時の目的関数の値が出力されます。 +最終的に推定されたパラメータは、 ``output/res.dat`` に出力されます。今の場合、 + +.. code-block:: + + fx = 1.2142360244883376e-09 + x1 = 0.9999764520155436 + x2 = 3.000012263854959 + +となり、最小値が再現されていることがわかります。 +なお、一連の計算を行う ``do.sh`` スクリプトが用意されています。 diff --git a/extra/function/doc/ja/source/tutorial/himmelblau.rst b/extra/function/doc/ja/source/tutorial/himmelblau.rst new file mode 100644 index 00000000..51969509 --- /dev/null +++ b/extra/function/doc/ja/source/tutorial/himmelblau.rst @@ -0,0 +1,153 @@ +Himmelblau関数の最小化 +================================ + +ここでは、2DMAT-Functions モジュールを用いたユーザプログラムを作成し、解析を行う方法を説明します。逆問題アルゴリズムは例としてNelder-Mead法を用います。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +サンプルファイルは ``sample/himmelblau`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``main.py`` + + メインプログラム。パラメータを ``input.toml`` ファイルから読み込んで解析を行う。 + +- ``input.toml`` + + ``main.py`` で利用する入力パラメータファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +- ``plot_colormap_2d.py`` + + 可視化ツール + +以下、これらのファイルについて説明したのち、実際の計算結果を紹介します。 + + +プログラムの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``main.py`` は 2DMAT-Functions モジュールを用いて解析を行うシンプルなプログラムです。 +プログラムの全体を以下に示します。 + +.. code-block:: python + + import numpy as np + + import py2dmat + import py2dmat.algorithm.mapper_mpi as mapper + from py2dmat.extra.function import Himmelblau + + info = py2dmat.Info.from_file("input.toml") + solver = Himmelblau(info) + runner = py2dmat.Runner(solver, info) + + alg = mapper.Algorithm(info, runner) + alg.main() + +プログラムではまず、必要なモジュールを import します。 + +- 2DMAT のメインモジュール ``py2dmat`` + +- 今回利用する逆問題解析アルゴリズム ``py2dmat.algorithm.mapper_mpi`` + +- 順問題ソルバーモジュール ``py2dmat.extra.function`` から Himmelblau クラス + +次に、解析で利用するクラスのインスタンスを作成します。 + +- ``py2dmat.Info`` クラス + + パラメータを格納するクラスです。 ``from_file`` クラスメソッドに TOML ファイルのパスを渡して作成することができます。 + +- ``Himmelblau`` クラス + + 2DMAT-Functions に用意されている Himmelblau関数のクラスです。Info クラスのインスタンスを渡して作成します。 + +- ``py2dmat.Runner`` クラス + + 順問題ソルバーと逆問題解析アルゴリズムを繋ぐクラスです。Solver クラスのインスタンスおよび Info クラスのパラメータを渡して作成します。 + +- ``py2dmat.algorithm.mapper_mpi.Algorithm`` クラス + + 逆問題解析アルゴリズムのクラスです。ここではグリッド全探索のクラスモジュール ``mapper_mpi`` を利用します。Runner のインスタンスを渡して作成します。 + +Solver, Runner, Algorithm の順にインスタンスを作成した後、Algorithm クラスの ``main()`` メソッドを呼んで解析を行います。 + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` の例を以下に示します。 +なお、アルゴリズムの種類を指定する ``algorithm.name`` パラメータの値は無視されます。 + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + + [solver] + + [runner] + [runner.log] + interval = 20 + + +計算実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します) + +.. code-block:: + + $ cd sample/himmelblau + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ mpiexec -np 4 python3 main.py + +ここではMPIを利用して4プロセスで計算を行っています。実行すると以下の様な出力がされます。 + +.. code-block:: + + Make ColorMap + Iteration : 1/240 + Iteration : 2/240 + Iteration : 3/240 + Iteration : 4/240 + Iteration : 5/240 + Iteration : 6/240 + Iteration : 7/240 + Iteration : 8/240 + Iteration : 9/240 + Iteration : 10/240 + ... + +結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` を図示することで、関数の値が小さいパラメータがどこにあるかを推定することができます。そのような 2次元パラメータ空間のプロットを作成するプログラムが ``plot_colormap_2d.py`` に用意されています。 + +.. code-block:: + + $ python3 plot_colormap_2d.py + +上記を実行すると ``ColorMapFig.png`` が作成され、Himmelblau関数の関数値を表す等高線の上に、各グリッド点で評価した関数値がカラーマップとしてプロットされます。 + +.. figure:: ../../../common/img/himmelblau_mapper.* + + 2次元パラメータ空間上での関数値のカラーマップ。 + diff --git a/extra/function/doc/ja/source/tutorial/index.rst b/extra/function/doc/ja/source/tutorial/index.rst new file mode 100644 index 00000000..8f24690c --- /dev/null +++ b/extra/function/doc/ja/source/tutorial/index.rst @@ -0,0 +1,17 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +チュートリアル +================================== + +このチュートリアルでは、Himmelblau関数の最小化問題を例として 2DMAT および 2DMAT-Functions ライブラリの使い方を解説します。あわせて、ユーザが独自の関数を定義して解析を行う方法を説明します。 + +逆問題解析アルゴリズムはグリッド探索の ``mapper`` モジュールを使います。その他のアルゴリズムについては 2DMAT のマニュアルを参照してください。 + +.. toctree:: + :maxdepth: 1 + + himmelblau + booth diff --git a/extra/function/pyproject.toml b/extra/function/pyproject.toml new file mode 100644 index 00000000..ab87bab1 --- /dev/null +++ b/extra/function/pyproject.toml @@ -0,0 +1,36 @@ +[tool.poetry] +name = "py2dmat-function" +version = "1.0-dev" +description = "Analytical function solver module for Py2DMAT: data-analysis software of quantum beam diffraction experiments for 2D material structure" +authors = ["2DMAT developers <2dmat-dev@issp.u-tokyo.ac.jp>"] +license = "GPL-3.0-or-later" + +readme = "README.md" +repository = "https://github.com/issp-center-dev/py2dmat-function" + +packages = [ + { include = "function", from = "src", to = "py2dmat/extra" } + ] + +[tool.poetry.dependencies] +python = ">=3.6.8" +numpy = "^1.14" +#mpi4py = {version = "^3", optional = true} +py2dmat = "^2" + +#[tool.poetry.extras] +#min_search = ["scipy"] +#bayes = ["physbo"] +#exchange = ["mpi4py"] +#all = ["scipy", "mpi4py", "physbo"] + +#[tool.poetry.dev-dependencies] +#black = "^22.3.0" +#pynvim = "^0.4.3" + +#[tool.poetry.scripts] +#py2dmat-function = "function._main:main" + +[build-system] +requires = ["poetry-core>=1.0.0"] +build-backend = "poetry.core.masonry.api" diff --git a/extra/function/sample/booth/booth.py b/extra/function/sample/booth/booth.py new file mode 100644 index 00000000..fe17e7c9 --- /dev/null +++ b/extra/function/sample/booth/booth.py @@ -0,0 +1,9 @@ +import numpy as np +import py2dmat.extra.function + +class Booth(py2dmat.extra.function.Solver): + def evaluate(self, xs: np.ndarray, args=()): + assert xs.shape[0] == 2 + x, y = xs + fx = (x + 2 * y - 7)**2 + (2 * x + y - 5)**2 + return fx diff --git a/extra/function/sample/booth/do.sh b/extra/function/sample/booth/do.sh new file mode 100644 index 00000000..a65cf432 --- /dev/null +++ b/extra/function/sample/booth/do.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +time python3 main.py diff --git a/extra/function/sample/booth/input.toml b/extra/function/sample/booth/input.toml new file mode 100644 index 00000000..2c14f9a6 --- /dev/null +++ b/extra/function/sample/booth/input.toml @@ -0,0 +1,17 @@ +[base] +dimension = 2 +output_dir = "output" + +[algorithm] +seed = 12345 + +[algorithm.param] +max_list = [6.0, 6.0] +min_list = [-6.0, -6.0] +num_list = [31, 31] + +[solver] + +[runner] +[runner.log] +interval = 20 diff --git a/extra/function/sample/booth/main.py b/extra/function/sample/booth/main.py new file mode 100644 index 00000000..becc574f --- /dev/null +++ b/extra/function/sample/booth/main.py @@ -0,0 +1,12 @@ +import numpy as np + +import py2dmat +import py2dmat.algorithm.min_search as min_search +from booth import Booth + +info = py2dmat.Info.from_file("input.toml") +solver = Booth(info) +runner = py2dmat.Runner(solver, info) + +alg = min_search.Algorithm(info, runner) +alg.main() diff --git a/extra/function/sample/himmelblau/do.sh b/extra/function/sample/himmelblau/do.sh new file mode 100644 index 00000000..b2c3e55b --- /dev/null +++ b/extra/function/sample/himmelblau/do.sh @@ -0,0 +1,4 @@ +#!/bin/sh + +#time python3 main.py +time mpiexec -np 4 python3 main.py diff --git a/extra/function/sample/himmelblau/input.toml b/extra/function/sample/himmelblau/input.toml new file mode 100644 index 00000000..2c14f9a6 --- /dev/null +++ b/extra/function/sample/himmelblau/input.toml @@ -0,0 +1,17 @@ +[base] +dimension = 2 +output_dir = "output" + +[algorithm] +seed = 12345 + +[algorithm.param] +max_list = [6.0, 6.0] +min_list = [-6.0, -6.0] +num_list = [31, 31] + +[solver] + +[runner] +[runner.log] +interval = 20 diff --git a/extra/function/sample/himmelblau/main.py b/extra/function/sample/himmelblau/main.py new file mode 100644 index 00000000..92dfc788 --- /dev/null +++ b/extra/function/sample/himmelblau/main.py @@ -0,0 +1,12 @@ +import numpy as np + +import py2dmat +import py2dmat.algorithm.mapper_mpi as mapper +from py2dmat.extra.function import Himmelblau + +info = py2dmat.Info.from_file("input.toml") +solver = Himmelblau(info) +runner = py2dmat.Runner(solver, info) + +alg = mapper.Algorithm(info, runner) +alg.main() diff --git a/extra/function/sample/himmelblau/plot_colormap_2d.py b/extra/function/sample/himmelblau/plot_colormap_2d.py new file mode 100644 index 00000000..e7cd25cc --- /dev/null +++ b/extra/function/sample/himmelblau/plot_colormap_2d.py @@ -0,0 +1,47 @@ +import numpy as np +import matplotlib.pyplot as plt + + +def himmel(x, y): + return (x ** 2 + y - 11) ** 2 + (x + y ** 2 - 7) ** 2 + + +npts = 201 +c_x, c_y = np.mgrid[-6 : 6 : npts * 1j, -6 : 6 : npts * 1j] +c_z = himmel(c_x, c_y) +levels = np.logspace(0.35, 3.2, 8) + +x = [] +y = [] +f = [] +file_input = open("output/ColorMap.txt", "r") +lines = file_input.readlines() +file_input.close() +for line in lines: + if line[0] != "/n": + data = line.split() + x.append(float(data[0])) + y.append(float(data[1])) + f.append(np.log10(float(data[2]))) + +vmin = np.amin(np.array(f)) +vmax = np.amax(np.array(f)) + +plt.contour(c_x, c_y, c_z, levels, colors="k", zorder=10.0, alpha=1.0, linewidths=0.5) +plt.scatter( + x, + y, + c=f, + s=50, + vmin=vmin, + vmax=vmax, + cmap="Blues_r", + linewidth=2, + alpha=1.0, + zorder=1.0, +) +plt.xlim(-6.0, 6.0) +plt.ylim(-6.0, 6.0) +plt.colorbar(label="log10(f)") +#plt.savefig("output/ColorMapFig.pdf") +plt.savefig("output/ColorMapFig.png") diff --git a/extra/function/sample/linear_regression/data.txt b/extra/function/sample/linear_regression/data.txt new file mode 100644 index 00000000..154881d0 --- /dev/null +++ b/extra/function/sample/linear_regression/data.txt @@ -0,0 +1,6 @@ +1.0 1.0 +2.0 3.0 +3.0 2.0 +4.0 4.0 +5.0 3.0 +6.0 5.0 diff --git a/extra/function/sample/linear_regression/do.sh b/extra/function/sample/linear_regression/do.sh new file mode 100644 index 00000000..a65cf432 --- /dev/null +++ b/extra/function/sample/linear_regression/do.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +time python3 main.py diff --git a/extra/function/sample/linear_regression/input.toml b/extra/function/sample/linear_regression/input.toml new file mode 100644 index 00000000..7851ee8e --- /dev/null +++ b/extra/function/sample/linear_regression/input.toml @@ -0,0 +1,17 @@ +[base] +dimension = 3 +output_dir = "output" + +[algorithm] +seed = 12345 + +#[algorithm.param] +#max_list = [ 1.0, 1.0, 1.0] +#min_list = [-1.0, -1.0, -1.0] +#num_list = [21, 21, 21] + +[solver] + +[runner] +[runner.log] +interval = 20 diff --git a/extra/function/sample/linear_regression/main.py b/extra/function/sample/linear_regression/main.py new file mode 100644 index 00000000..52cf3b9f --- /dev/null +++ b/extra/function/sample/linear_regression/main.py @@ -0,0 +1,18 @@ +import numpy as np + +import py2dmat +#import py2dmat.algorithm.mapper_mpi as mapper +import py2dmat.algorithm.min_search as min_search +from py2dmat.extra.function import LinearRegression +import py2dmat.domain + +data = np.loadtxt("data.txt") + +info = py2dmat.Info.from_file("input.toml") +solver = LinearRegression(info, xdata=data[:,0], ydata=data[:,1]) +runner = py2dmat.Runner(solver, info) + +region = py2dmat.domain.Region(param={"min_list": [-1,-1,-1], "max_list": [1,1,1]}) + +alg = min_search.Algorithm(info, runner, region) +alg.main() diff --git a/extra/function/src/function/Ackley.py b/extra/function/src/function/Ackley.py new file mode 100644 index 00000000..8ee4e007 --- /dev/null +++ b/extra/function/src/function/Ackley.py @@ -0,0 +1,35 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import numpy as np +import py2dmat +from .function import Solver + +def ackley(xs: np.ndarray) -> float: + """Ackley's function in arbitrary dimension + + It has one global minimum f(xs)=0 at xs=[0,0,...,0]. + It has many local minima. + """ + a = np.mean(xs ** 2) + a = 20 * np.exp(-0.2 * np.sqrt(a)) + b = np.cos(2.0 * np.pi * xs) + b = np.exp(0.5 * np.sum(b)) + return 20.0 + np.exp(1.0) - a - b + +class Ackley(Solver): + def __init__(self, info): + super().__init__(info, fn=ackley) diff --git a/extra/function/src/function/Himmelblau.py b/extra/function/src/function/Himmelblau.py new file mode 100644 index 00000000..76eda9c6 --- /dev/null +++ b/extra/function/src/function/Himmelblau.py @@ -0,0 +1,33 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import numpy as np +import py2dmat +from .function import Solver + +def himmelblau(xs: np.ndarray) -> float: + """Himmelblau's function + + It has four global minima f(xs) = 0 at + xs=[3,2], [-2.805118..., 3.131312...], [-3.779310..., -3.2831860], and [3.584428..., -1.848126...]. + """ + assert xs.shape[0] == 2, f"ERROR: himmelblau expects d=2 input, but receives d={xs.shape[0]} one" + x, y = xs + return (x ** 2 + y - 11.0) ** 2 + (x + y ** 2 - 7.0) ** 2 + +class Himmelblau(Solver): + def __init__(self, info): + super().__init__(info, fn=himmelblau) diff --git a/extra/function/src/function/LinearRegression.py b/extra/function/src/function/LinearRegression.py new file mode 100644 index 00000000..849d8afe --- /dev/null +++ b/extra/function/src/function/LinearRegression.py @@ -0,0 +1,49 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import numpy as np +import py2dmat +from .function import Solver + +class _LinearRegression: + def __init__(self, xdata, ydata): + self.xdata = np.array(xdata) + self.ydata = np.array(ydata) + self.n = len(xdata) + + def __call__(self, xs: np.ndarray) -> float: + """ Negative log likelihood of linear regression with Gaussian noise N(0,sigma) + + y = ax + b + + example: + trained by xdata = [1, 2, 3, 4, 5, 6] and ydata = [1, 3, 2, 4, 3, 5]. + + Model parameters (a, b, sigma) are corresponding to xs as the following, + a = xs[0], b = xs[1], log(sigma**2) = xs[2] + + It has a global minimum f(xs) = 1.005071.. at + xs = [0.628571..., 0.8, -0.664976...]. + """ + assert xs.shape[0] == 3, f"ERROR: regression expects d=3 input, but receives d={xs.shape[0]} one" + + a, b, w = xs + return 0.5 * (self.n * w + np.sum((a * self.xdata + b - self.ydata) ** 2) / np.exp(w)) + +class LinearRegression(Solver): + def __init__(self, info, xdata, ydata): + super().__init__(info) + self.set_function(_LinearRegression(xdata, ydata)) diff --git a/extra/function/src/function/Quadratics.py b/extra/function/src/function/Quadratics.py new file mode 100644 index 00000000..2cfc42a6 --- /dev/null +++ b/extra/function/src/function/Quadratics.py @@ -0,0 +1,30 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import numpy as np +import py2dmat +from .function import Solver + +def quadratics(xs: np.ndarray) -> float: + """quadratic (sphear) function + + It has one global miminum f(xs)=0 at xs = [0,0,...,0]. + """ + return np.sum(xs * xs) + +class Quadratics(Solver): + def __init__(self, info): + super().__init__(info, fn=quadratics) diff --git a/extra/function/src/function/Quartics.py b/extra/function/src/function/Quartics.py new file mode 100644 index 00000000..7d8d6d5e --- /dev/null +++ b/extra/function/src/function/Quartics.py @@ -0,0 +1,32 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import numpy as np +import py2dmat +from .function import Solver + +def quartics(xs: np.ndarray) -> float: + """quartic function with two minimum + + It has two global minimum f(xs)=0 at xs = [1,1,...,1] and [0,0,...,0]. + It has one suddle point f(0,0,...,0) = 1.0. + """ + + return np.mean((xs - 1.0) ** 2) * np.mean((xs + 1.0) ** 2) + +class Quartics(Solver): + def __init__(self, info): + super().__init__(info, fn=quartics) diff --git a/extra/function/src/function/Rosenbrock.py b/extra/function/src/function/Rosenbrock.py new file mode 100644 index 00000000..5928146e --- /dev/null +++ b/extra/function/src/function/Rosenbrock.py @@ -0,0 +1,30 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import numpy as np +import py2dmat +from .function import Solver + +def rosenbrock(xs: np.ndarray) -> float: + """Rosenbrock's function + + It has one global minimum f(xs) = 0 at xs=[1,1,...,1]. + """ + return np.sum(100.0 * (xs[1:] - xs[:-1] ** 2) ** 2 + (1.0 - xs[:-1]) ** 2) + +class Rosenbrock(Solver): + def __init__(self, info): + super().__init__(info, fn=rosenbrock) diff --git a/extra/function/src/function/__init__.py b/extra/function/src/function/__init__.py new file mode 100644 index 00000000..c6cb7cb3 --- /dev/null +++ b/extra/function/src/function/__init__.py @@ -0,0 +1,8 @@ +from .function import Solver + +from .Quadratics import Quadratics +from .Quartics import Quartics +from .Ackley import Ackley +from .Rosenbrock import Rosenbrock +from .Himmelblau import Himmelblau +from .LinearRegression import LinearRegression diff --git a/extra/function/src/function/function.py b/extra/function/src/function/function.py new file mode 100644 index 00000000..d7bf993f --- /dev/null +++ b/extra/function/src/function/function.py @@ -0,0 +1,69 @@ +# 2DMAT -- Data-analysis software of quantum beam diffraction experiments for 2D material structure +# Copyright (C) 2020- The University of Tokyo +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see http://www.gnu.org/licenses/. + +import os +import numpy as np +import py2dmat + +# type hints +from pathlib import Path +from typing import Callable, Optional, Dict + + +class Solver: + root_dir: Path + output_dir: Path + proc_dir: Path + work_dir: Path + _name: str + dimension: int + timer: Dict[str, Dict] + _func: Optional[Callable[[np.ndarray], float]] + + def __init__(self, + info: Optional[py2dmat.Info] = None, + fn: Optional[Callable[[np.ndarray], float]] = None) -> None: + """ + Initialize the solver. + + Parameters + ---------- + info: Info + fn: callable object + """ + self.root_dir = info.base["root_dir"] + self.output_dir = info.base["output_dir"] + self.proc_dir = self.output_dir / str(py2dmat.mpi.rank()) + self.work_dir = self.proc_dir + + self.dimension = info.solver.get("dimension") or info.base.get("dimension") + + self._name = "function" + self._func = fn + + self.timer = {"prepare": {}, "run": {}, "post": {}} + + @property + def name(self) -> str: + return self._name + + def evaluate(self, x: np.ndarray, args = (), nprocs: int = 1, nthreads: int = 1) -> float: + if self._func is None: + raise RuntimeError("ERROR: function is not set. Make sure that `set_function` is called.") + return self._func(x) + + def set_function(self, f: Callable[[np.ndarray], float]) -> None: + self._func = f diff --git a/extra/function/tests/.placeholder b/extra/function/tests/.placeholder new file mode 100644 index 00000000..e69de29b