{"id":19015258,"url":"https://github.com/americocunhajr/ceopt","last_synced_at":"2026-02-17T19:02:17.545Z","repository":{"id":253346170,"uuid":"828350333","full_name":"americocunhajr/CEopt","owner":"americocunhajr","description":"CEopt is a Matlab routine for non-convex optimization using the Cross-Entropy method and augmented Lagrangian formulation.","archived":false,"fork":false,"pushed_at":"2025-04-04T18:00:38.000Z","size":12741,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-06T16:46:08.944Z","etag":null,"topics":["cross-entropy-method","matlab-toolbox","nonconvex-optimization","optimization","optimization-algorithm","optimization-algorithms","optimization-framework","optimization-library","optimization-methods","optimization-technique","optimization-tools"],"latest_commit_sha":null,"homepage":"https://ceopt.org/","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/americocunhajr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-13T21:42:46.000Z","updated_at":"2025-04-04T18:00:41.000Z","dependencies_parsed_at":"2025-04-03T17:21:00.121Z","dependency_job_id":"8110dbaf-2df1-42b5-a5f1-5ccd8859f04c","html_url":"https://github.com/americocunhajr/CEopt","commit_stats":null,"previous_names":["americocunhajr/ceopt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/americocunhajr/CEopt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americocunhajr%2FCEopt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americocunhajr%2FCEopt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americocunhajr%2FCEopt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americocunhajr%2FCEopt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/americocunhajr","download_url":"https://codeload.github.com/americocunhajr/CEopt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americocunhajr%2FCEopt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29554392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T18:16:07.221Z","status":"ssl_error","status_checked_at":"2026-02-17T18:16:04.782Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-entropy-method","matlab-toolbox","nonconvex-optimization","optimization","optimization-algorithm","optimization-algorithms","optimization-framework","optimization-library","optimization-methods","optimization-technique","optimization-tools"],"created_at":"2024-11-08T19:36:32.177Z","updated_at":"2026-02-17T19:02:17.528Z","avatar_url":"https://github.com/americocunhajr.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Cross-Entropy Optimizer\n\n**CEopt: Cross-Entropy Optimizer** is a Matlab package that implements a framework for non-convex optimization using the Cross-Entropy (CE) method. Due to the algorithm's relative simplicity, CEopt provides a transparent \"gray-box\" optimization solver with intuitive control parameters. It effectively handles both equality and inequality constraints through an augmented Lagrangian method, offering robustness and scalability for moderately sized complex problems. **CEopt**'s applicability and effectiveness are demonstrated through select case studies, making it a practical addition to optimization research and application toolsets.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"logo/CEoptStructure.png\" width=\"80%\"\u003e\n\u003c/p\u003e\n\n### Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Examples](#examples)\n- [Reproducibility](#reproducibility)\n- [Documentation](#documentation)\n- [Authors](#authors)\n- [Citing CEopt](#citing-ceopt)\n- [License](#license)\n- [Institutional Support](#institutional-support)\n- [Funding](#funding)\n- [Contact](#contact)\n\n### Overview\n**CEopt** was developed to provide a robust and scalable solution for non-convex optimization problems using the Cross-Entropy method. More details can be found in the following paper:\n- **A. Cunha Jr, M. V. Issa, J. C. Basilio, and J. G. Telles Ribeiro**, *CEopt: A MATLAB Package for Non-convex Optimization with the Cross-Entropy Method*, PrePrint, \tarXiv:2409.00013, 2024, DOI https://doi.org/10.48550/arXiv.2409.00013\n\nPreprint available at: [https://doi.org/10.48550/arXiv.2409.00013](https://doi.org/10.48550/arXiv.2409.00013)\n\n### Features\n- Implements Cross-Entropy method for non-convex optimization\n- Handles equality and inequality constraints using augmented Lagrangian method\n- Transparent \"gray-box\" optimization solver with intuitive control parameters\n- Robust and scalable for moderately sized complex problems\n- Demonstrated applicability through select case studies\n\n### Installation\nTo install and get started with **CEopt**, follow these steps:\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/americocunhajr/CEopt.git\n   ```\n2. Navigate to the package directory:\n   ```bash\n   cd CEopt/CEopt-1.0\n   ```\n3. Copy the `CEopt.m` file to your working directory:\n   ```bash\n   cp CEopt.m 'path_to_working_directory'\n   ```\n\nAlternatively, you can add the `CEopt` directory to the Matlab path:\n1. Open Matlab and type\n   ```bash\n   addpath 'path_to_CEopt_directory/CEopt/CEopt-1.0'\n   ```\nThis will add `CEopt` to the path for the running section. Every time MATLAB is restarted this procedure must be repeated.\n\n### Usage\nTo run CEopt, use the following commands in Matlab:\n   ```bash\n   [Xopt,Fopt,ExitFlag,CEstr] = CEopt(fun,xmean0,sigma0,lb,ub,nonlcon,CEstr)\n   ```\nEach parameter is described as follows:\n- `fun`: Function handle for the objective function. This function must accept a 1 x Nvars row  vector  (representing a single sample) or an M x Nvars matrix (representing M samples with variables in columns) as input and return a scalar value or a row vector of M scalar values (for vectorized operations) respectively.\n- `xmean0`: Initial mean of the design variables distributions.\n- `sigma0`: Initial standard deviations for the design variables distributions.\n- `lb`: Lower bounds for the design variables.\n- `ub`: Upper bounds for the design variables.\n- `nonlcon`: Function handle for the nonlinear constraints. Returns two arrays `G` (inequalities) and `H` (equalities).\n- `CEstr`: Structure with settings for the CEopt algorithm.\n\nThe CEstr structure allows for extensive customization of the CE optimization process. Here's a breakdown of its fields:\n\n- `Verbose`: Boolean flag to enable detailed output during optimization.\n- `isConstrained`: Set to true if there are constraints defined by nonlcon.\n- `isVectorized`: Set to true if fun and nonlcon can evaluate multiple rows of X in a single call.\n- `Nvars`: Number of variables in the optimization problem.\n- `EliteFactor`: Proportion of the population considered elite.\n- `Nsamp`: Number of samples used in each iteration of the optimization.\n- `MaxIter`: Maximum number of iterations for the optimization process.\n- `MaxStall`: Maximum number of iterations without improvement before termination.\n- `MaxFcount`: Maximum number of function evaluations allowed.\n- `MinFval`: Target objective function value for early stopping.\n- `TolAbs`: Absolute tolerance on the change in the objective function value for convergence.\n- `TolRel`: Relative tolerance on the change in the objective function value for convergence.\n- `TolCon`: Tolerance on the feasibility of constraints.\n- `TolFun`: Tolerance on the change in function value for convergence.\n- `alpha`: Smoothing parameter for the mean update.\n- `beta`: Smoothing parameter for the standard deviation update.\n- `q`: Smoothing parameter for standard deviation update.\n- `NonlconAlgorithm`: Algorithm used for handling nonlinear constraints.\n- `InitialPenalty`: Initial penalty coefficient for constraint violation.\n- `PenaltyFactor`: Scaling factor for the penalty coefficient.\n\nThis extensive set of parameters and settings enables users to finely tune the CE optimization to their specific needs and problem characteristics.\n\n### Examples\n\nBelow are step-by-step guides demonstrating how to use CEopt for different optimization tasks.\n\n```matlab\n% Unconstrained optimization with 2 variables\n\n% objective function\nF = @(x)PeaksFunc(x);\n\n% bound for design variables\nlb = [-3; -3];\nub = [ 3;  3];\n\n% initialize mean and std. dev. vectors\nmu0    = lb + (ub-lb).*rand(2,1);\nsigma0 = 5*(ub-lb);\n        \n% define parameters for the CE optimizer\nCEstr.isVectorized = 1;       % Vectorized function\nCEstr.EliteFactor  = 0.1;     % Elite samples percentage\nCEstr.Nsamp        = 50;      % Number of samples\nCEstr.MaxIter      = 80;      % Maximum of iterations\nCEstr.TolAbs       = 1.0e-2;  % Absolute tolerance\nCEstr.TolRel       = 1.0e-2;  % Relative tolerance\nCEstr.alpha        = 0.7;     % Smoothing parameter\nCEstr.beta         = 0.8;     % Smoothing parameter\nCEstr.q            = 10;      % Smoothing parameter\n\n% CE optimizer\ntic\n[Xopt,Fopt,ExitFlag,CEstr] = CEopt(F,mu0,sigma0,lb,ub,[],CEstr)\ntoc\n\n% objective function\nfunction F = PeaksFunc(x)\n    x1 = x(:,1);\n    x2 = x(:,2);\n     F = 3*(1-x1).^2.*exp(-x1.^2 - (x2+1).^2) ...\n       - 10*(x1/5 - x1.^3 - x2.^5).*exp(-x1.^2 - x2.^2)...\n       - (1/3)*exp(-(x1+1).^2 - x2.^2);\nend\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"logo/Fig6-Example2.png\" width=\"80%\"\u003e\n\u003c/p\u003e\n\n```matlab\n% Constrained optimization with 2 variables\n\n% objective function and constraints\nF       = @PatternSearchFunc;\nnonlcon = @ConicConstraints;\n\n% bound for design variables\nlb  = [-6 -4];\nub  = [ 2  4];\nmu0 = [-4  2];\n\n% cross-entropy optimizer struct\nCEstr.isVectorized  = 1;       % vectorized function\nCEstr.TolCon        = 1.0e-6;  % relative tolerance\n\ntic\n[Xopt,Fopt,ExitFlag,CEstr] = CEopt(F,mu0,[],lb,ub,nonlcon,CEstr)\ntoc\n\n% objective function\nfunction F = PatternSearchFunc(x)\n    x1 = x(:,1);\n    x2 = x(:,2);\n    F = zeros(size(x1,1),1);\n    for i = 1:size(x,1)\n        if  x1(i) \u003c -5\n            F(i) = (x1(i)+5).^2 + abs(x2(i));\n        elseif x1(i) \u003c -3\n            F(i) = -2*sin(x1(i)) + abs(x2(i));\n        elseif x1(i) \u003c 0\n            F(i) = 0.5*x1(i) + 2 + abs(x2(i));\n        elseif x1 \u003e= 0\n            F(i) = .3*sqrt(x1(i)) + 5/2 + abs(x2(i));\n        end\n    end\nend\n\n% equality and inequality constraints\nfunction [G,H] = ConicConstraints(x)\n    x1 = x(:,1);\n    x2 = x(:,2);\n    G  = 2*x1.^2 + x2.^2 - 3;\n    H  = (x1+1).^2 - (x2/2).^4;\nend\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"logo/Fig13-Example6.png\" width=\"80%\"\u003e\n\u003c/p\u003e\n\n#### Note on Stochastic Nature of CEopt\nThe CE method, which underpins the CEopt package, is inherently stochastic. This means that each run of the optimization process might follow a different trajectory towards the optimum due to the random sampling involved in the method. Therefore, it is entirely normal for repeated executions of the same optimization task to yield different paths or convergence profiles. Users are encouraged to consider multiple runs or adjust the `sigma0` parameter to manage the exploration-exploitation balance and potentially achieve more consistent results.\n\n### Reproducibility\nThe tutorials of **CEopt** package are fully reproducible. You can find a fully reproducible capsule of the simulations on \u003ca href=\"https://codeocean.com/capsule/0007851/tree\" target=\"_blank\"\u003eCodeOcean\u003c/a\u003e.\n\n### Documentation\nThe routines in **CEopt** package are well-commented to explain their functionality. Each routine includes a description of its purpose, as well as inputs and outputs. Detailed documentation about the code functionality can be found in paper.\n\n### Authors\n- Americo Cunha Jr\n- Marcos Vinicius Issa\n- Julio Cesar de Castro Basilio\n- Jose Geraldo Telles Ribeiro\n\n### Citing CEopt\nIf you use **CEopt** in your research, please cite the following publication:\n- **A. Cunha Jr, M. V. Issa, J. C. Basilio, and J. G. Telles Ribeiro**, *CEopt: A MATLAB Package for Non-convex Optimization with the Cross-Entropy Method*, PrePrint, \tarXiv:2409.00013, 2024, DOI https://doi.org/10.48550/arXiv.2409.00013\n\n```\n@article{CunhaJr2024CEopt,\n   author  = {A {Cunha~Jr} and M. V. Issa and J. C. Basilio and J. G. {Telles Ribeiro}},\n   title   = \"{CEopt: A MATLAB Package for Non-convex Optimization with the Cross-Entropy Method}\",\n   journal = {PrePrint},\n   year    = {2024},\n   volume  = {arXiv:2409.00013},\n   pages   = {~},\n   doi    = {10.48550/arXiv.2409.00013},\n   url    = {https://ceopt.org},\n}\n```\n\n### License\n**CEopt** is released under the GNU General Public License v3.0. See the LICENSE file for details. All new contributions must be made under the MIT license.\n\n\u003cimg src=\"logo/GPLv3_Logo.png\" width=\"20%\"\u003e \n\n### Institutional support\n\n\u003cimg src=\"logo/logo_uerj.png\" width=\"12%\"\u003e \u0026nbsp; \u0026nbsp; \u003cimg src=\"logo/logo_lncc.png\" width=\"25%\"\u003e  \n\n### Funding\n\n\u003cimg src=\"logo/cnpq.png\" width=\"20%\"\u003e \u0026nbsp; \u0026nbsp; \u003cimg src=\"logo/capes.png\" width=\"10%\"\u003e  \u0026nbsp; \u0026nbsp; \u0026nbsp; \u003cimg src=\"logo/faperj.png\" width=\"25%\"\u003e\n\n### Contact\nFor any questions or further information, please contact:\n\nAmerico Cunha Jr: americo.cunha@uerj.br\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericocunhajr%2Fceopt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famericocunhajr%2Fceopt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericocunhajr%2Fceopt/lists"}